Webhooks security

Authentication Header

We provide the ability for you to define your custom authentication in the webhook header when you are creating a new webhook subscription. If you use a custom authentication header, when we send the notification to your service, the custom authentication header will be included in the header of the callback.

We support 3 different types of custom authentication:

1. Basic authentication header using username and password
2. Custom authentication header using self-defined header and value
3. OAuth 2.0 Client Credential using access token exchanged from a specified clientId and clientSecret

To illustrate the use of a custom authentication header, below are two example calls for notification we make to your service with and without custom authentication.

Without custom authentication header:

cURL

curl -v -H "Accept: application/json" -H "Content-Type: application/json" --data '{"id":"example"}' https://your-host.com/path/to/webhook

With custom authentication header:

cURL

curl -v -H "CUSTOM_SECURITY_HEADER_NAME: CUSTOM_SECURITY_KEY" -H "Accept: application/json" -H "Content-Type: application/json" --data '{"id":"example"}' https://your-host.com/path/to/webhook

Where CUSTOM_SECRUITY_HEADER_NAME will be the value you defined in callbackAuthentication.headerName and CUSTOM_SECURITY_KEY will be the value you defined in callbackAuthentication.headerValue when creating a new webhook subscription. In either cases, we expect your service to response with HTTP 202 to acknowledge you’ve received the notification

We expect a valid certificate is used for HTTPS connect and we do not accept self-signed certificates.

Payload signature

SmartRecruiters can sign each notification with HMAC SHA256 signature if you setup secret key for subscription. Please check Generate secret key for a webhook subscription. for more details.