---
title: "Generate a secret key for a webhook subscription."
method: POST
path: "/subscriptions/{id}/secret-key"
tags: ["subscriptions"]
---

# Generate a secret key for a webhook subscription.

`POST /subscriptions/{id}/secret-key`

## Request

- Base URL: `https://api.smartrecruiters.com/webhooks-api/v201907`
- URL: `https://api.smartrecruiters.com/webhooks-api/v201907/subscriptions/{id}/secret-key`
- Auth: one of:
  - API key in header `x-smarttoken`
  - OAuth 2
    - Authorization code: `https://www.smartrecruiters.com/identity/oauth/allow`
    - Token URL: `https://api.smartrecruiters.com/identity/oauth/token` scopes: `webhooks_write`, `webhooks_manage`

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:

```
$SIGNATURE_SCHEMA=$SIGNATURE_1;$SIGNATURE_SCHEMA=$SIGNATURE_2...
```

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 = "<http://smartrecruiters.com/endpoint>; 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.<http://smartrecruiters.com/endpoint>; 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:
`v1=2e9291f10d44ca10204a4cd81b05d73b6a316b2b605d4e2e0e0b37b40198ce1f`

## Response `201`

Secret key sucessfully generated.

- SecretKeyPayload
  - `secretKey` string

## Other responses

- `403`: With codes: * **NO_PERMISSION_TO_MANAGE_WEBHOOKS** when no permission to manage webhook subscriptions * **SECRET_KEYS_LIMIT_EXCEEDED** when secret keys limit for subscription is exceeded
- `404`: Subscription not found.

---

[API](https://skmtc.dev/smartrecruiters/apis/webhooks.md) - [All operations](https://skmtc.dev/smartrecruiters/apis/webhooks/llms.txt) - [OpenAPI document](https://skmtc.dev/smartrecruiters/apis/webhooks/revisions/52d7f629b537?raw)