Receiving webhook notifications

Every webhook notification you receive contains information about type of event and its version in the headers. The id of the changed resource is provided in the body. Example body:

  "id": "string"

You will also find a header called Link in the notification request. Use this link to retrieve the current state of the resource via one of our Customer API endpoints.

In notification you can also find smartrecruiters-signature HMAC SHA256 header with payload signature. See more at this page.

We consider a notification to be successfully delivered when we receive a 202 response from your server for each notification. We expect to get the response within 5 seconds. If we don’t get response during this period, we will considered webhook delivery as failed. This information can also be found under the “Callbacks” tab of the POST /subscriptions endpoint in Live Docs (response description) .

Any other response code or client timeout will be considered as a failed delivery. We will attempt to re-deliver a webhook notification up to 10 times from the initial failure. The retry cadence will follow an exponential back-off strategy as following:

  • 1 minute after first delivery failure
  • 3 minutes after second delivery failure
  • 10 minutes after third delivery failure
  • 45 minutes after fourth delivery failure
  • 120 minutes (2 hours) after fifth delivery failure
  • … up to 1440 minutes (24 hours) after ninth delivery failure

*Webhook notifications may be re-delivered with a longer delay in case of excessive subscriber failures.

Additionally, we will also send a notification email to the email address you have set in alertEmailAddress field when your service was creating the webhook subscription when the webhook notification fails to deliver. In the events which your server failed to receive the webhook notification after the retries, you have the option to retrieve the webhook events log from the past 30 days, for both failed and success webhook events with:

GET /subscriptions/{id}/callbacks-log