Generate a secret key for a webhook subscription.

We allow you to generate a secret key for the subscription. You can use it to verify the author of callback messages. When you
have a secret key already defined - a creation of a new one will make the old one deprecated - it will still be active for 24 hours
though. You can have up to 16 non-expired secret keys.

A signature will be included in header smartrecruiters-signature of callback request. Additionally, we will send
smartrecruiters-timestamp header with timestamp (seconds) of request.

smartrecruiters-signature header value has the following format:


As you may notice there may be multiple signatures included in the header. It can be caused by one or both:

  • having multiple active keys
  • smartrecruiters providing multiple signatures per key with different signature schemes. We may use it in the
    future to deliver new algorithm of signature creation without breaking backward compatibility.
    Every segment of header value is delimited by ; character

Currently, we support and send the following signature ($SIGNATURE_SCHEMA):

1) v1

Signature calculated using HMAC with SHA256 algorithm. Hash should be calculated from the following elements
concatenated by the . character:

  • smartrecruiters-timestamp header value
  • request body
  • event-id header value
  • event-name header value
  • event-version header value
  • link header value

Order of these elements is important. In the absence of a header please use an empty string as its value.

For example, assume we have:

  • One active secret key: HeBVky2bccvvkcXPimH8c
  • Callback request:
    • headers:
      • content-type: application/json
      • smartrecruiters-signature: "v1=2e9291f10d44ca10204a4cd81b05d73b6a316b2b605d4e2e0e0b37b40198ce1f"
      • smartrecruiters-timestamp = "1574080897"
      • event-id = "123"
      • link = "; rel=self"
      • event-name = "application.created"
      • event-version = "v201910"
    • body: {"job_id":"jid","candidate_id": "cid"}

hash should be calculated from value:

1574080897.{"job_id":"jid","candidate_id":"cid"}.123.application.created.v201910.<>; rel=self

and after using HMAC and SHA256 it should give you hash : 2e9291f10d44ca10204a4cd81b05d73b6a316b2b605d4e2e0e0b37b40198ce1f,

so that smartrecruiters-signature header in the callback request will have value:

Click Try It! to start a request and see the response here!