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.

🚧

Potential Automatic Suspension of Webhooks Due to Delivery Failures

Please be aware that if a series of notifications fails to be delivered successfully, your webhooks may be subject to automatic suspension. For more detailed information regarding this policy, kindly refer to the following section: Automatic webhook subscription suspension

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

Automatic webhook subscription suspension

We may automatically suspend your webhook subscription for two reasons:

1. Response with a 410 HTTP Status Code: This indicates that the target resource is no longer available at its origin. We will suspend the subscription immediately upon receiving this status code.
2. Excessive Error Responses from Your Server: If your server is unable to process our notifications and we consistently receive errors, it could lead to suspension. Specifically, if we receive more than 500 error responses and not a single successful response from your server over the past 14 days, we will consider your server as unhealthy and suspend the subscription.

In the event that your subscription is suspended, you have the option to reactivate it - how to activate webhook subscription