Receive Push Events

Article
05/08/2023

LinkedIn Middleware has enabled the ability for developer applications to subscribe to changes made by their customers in LinkedIn products in real time. When the subscribed event happens, a HTTP POST request will be sent to the callback URL registered by the developer for the customer. This will allow developers to receive data only when changes happen and no longer continuously poll the LinkedIn APIs to determine any changes.

When an action is taken within a LinkedIn product which corresponds to the specific event type, a push notification will be sent to the developer’s registered callback URL. This notification will provide a unique identifier corresponding to the event within LinkedIn. This ID can then be used by your application to make a secondary API call to retrieve more data and information about the specific event.

Getting Started

Registering a Developer Application

In order to successfully receive push notifications from LinkedIn, you must have a registered developer application . If your product is already integrated on the LinkedIn Middleware platform, you will likely be using the same keys for development and production as provisioned before.

Setting up Callback URLs

You need to prepare a URL that can be used as a callback URL and is accessible by LinkedIn’s servers. LinkedIn also requires every customer on your platform to have a unique callback URL to receive POST data whenever subscribed events happen within LinkedIn. Ensure that the callback URL is secure https with port 80 or 443. LinkedIn does not support re-using the same callback URL for multiple customers or providing multiple callback URLs for one customer.

Registering your URLs

You will register customer callback URLs as part of Configuring Customer Middleware Integrations . This process is also used during development using your test customer app credentials.

Developers are only able to listen to events related to customers who have provisioned the developer access to listen to the specified event type.

Receiving Push Notifications

Validating the Request

To generate an "HMACSHA256" signature, LinkedIn uses:

Your developer application secret as the secret key for encryption
Prefixes "hmacsha256=" to the request payload to get the encryption string

UTF-8 encoding is used for both the above steps.

This signature is then included as an "X-LI-Signature" header in the HTTP POST request sent from LinkedIn servers. Use the secret key associated with your API Key in order to compute and compare with the signature included in the request.

Note

We are unable to share our IP range to validate incoming push events. We recommend domain allowlist over IP allowlist.

The computed HMAC can be tested using a free HMAC Generator. Using "hmacsha256=" and appending the request payload, the computed HMAC should match the X-LI-Signature from the request when using the associated secret key.

Example: hmacsha256={"id":"59a92119-3b72-4d2f-8e12-137a13180df6-1","type":"EXPORT_CANDIDATE_PROFILE","expiresAt":1481402799192}

POST https://{provided unique callback URL}

Request Body Fields

Field	Description	Format	Required
type	Type of notification	String	Yes
id	Unique id of the export candidate request	String	Yes
expires_at	Time when this "id" will expire. If not provided, the "id" will never expire.	Epoch in Milliseconds (UTC)	Optional

Sample Request

"Content-Type":"application/json",
"X-LI-Signature":"d3756e445a8065c0f38c2182c502f8229800eb2c6a9f3b4a1fdf152af867e6fc",
"Content-Length":"107",
"Connection":"Keep-Alive",
"Accept-Encoding":"gzip,deflate"


{
   "id":"59a92119-3b72-4d2f-8e12-137a13180df6-1",
   "type":"EXPORT_CANDIDATE_PROFILE",
   "expiresAt":1481402799192
}

Response Codes

Your URL should return one of the expected HTTP responses when a call is received from LinkedIn.

Result	HTTP Response Code	HTTP Response Payload
Notification was successfully received	200 OK	None
Notification was received, but payload was not understood	400 Bad Request	JSON result with the field “errorMessage”. This string field should be the reason the request payload was not understood. Example: { "errorMessage": "Failed to get id from request payload."}
System encountered an error while processing the request	500 Internal Server Error	None

Retry Logic

If a push notification request sent to the registered callback URL receives an unsuccessful response (“200 OK”), then LinkedIn will retry sending the request.

Retry Frequency	Delay Between Retry Requests
Maximum of five retry attempts	300 seconds between retry attempts

After the maximum number of retry attempts have been sent, the notification will be dropped. Each retry from LinkedIn will have a unique ID value. Developers should be validating data received when using the ID to make subsequent API calls to handle deduplication of updates that may result from retry attempts.