---
title: "Subscribe to a webhook."
method: POST
path: "/subscriptions"
tags: ["subscriptions"]
---

# Subscribe to a webhook.

`POST /subscriptions`

## Request

- Base URL: `https://api.smartrecruiters.com/webhooks-api/v201907`
- URL: `https://api.smartrecruiters.com/webhooks-api/v201907/subscriptions`
- 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`

Please be aware that before any event is delivered each subscription needs to be activated.

See [subscription activation](subscriptionsactivate-1).

We do limit number of subscriptions each subscriber can register. It means that:

* individual user can register up to 20 subscriptions
* OAuth application can register up to 20 subscriptions on behalf of a single user

Alerting email address and callback authentication properties are optional.

## Request body

- SubscriptionRequest
  - `name` string, nullable
  - `description` string, nullable
  - `callbackUrl` string, https_url, required
  - `events` EventName[], required
  - `alertingEmailAddress` string, email
  - `callbackAuthentication` union
    - object
      - `type` 'basic'
      - `username` string
      - `password` string
    - object
      - `type` 'header'
      - `headerName` string: Custom header name starting with "x-"
      - `headerValue` string
    - object: When `CallbackAuthentication` is set to `oauth2`, every call made to the webhook callback URL will include header `'authorization': Bearer access_token_value`
      - `type` 'oauth2'
      - `clientId` string: OAuth2 client ID used for token request
      - `clientSecret` string: OAuth2 client secret used for token request
      - `scope` string: OAuth2 scopes used for token request. If not provided, the token request will not include the scope parameter. If it's provided, the payload of the request to the token service will be extended with `&scope=provided_scope`.
      - `tokenServiceUrl` string, https_url: OAuth2 token service URL. This service is expected to consume `application/x-www-form-urlencoded` content type. The payload will consist of `client_id=provided_client_id&client_secret=provided_client_secret&grant_type=client_credentials` If the scope parameter is defined, then the payload will be extended with `&scope=provided_scope`. As a result, the service should return JSON containing information about the access token in the form: ``` { "access_token": "access_token_value", "expires_in": 3600 } ``` Where `access_token` is a token value and `expires_in` is a number of seconds until the token expiration.

## Response `201`

Webhook subscription created.

- Subscription
  - `id` string
  - `name` string, nullable
  - `description` string, nullable
  - `callbackUrl` string, https_url, required
  - `events` Event[], required
    - `name` 'job.created' | 'job.updated' | 'job.status.updated' | 'job.hiring-team.updated' | 'job.ad.created' | 'job.ad.updated' | 'job.ad.postings.updated' | 'position.created' | 'position.updated' | 'position.deleted' | 'application.created' | 'application.status.updated' | 'application.fields.updated' | 'application.onboarding-status.updated' | 'application.attachment.created' | 'application.source.updated' | 'candidate.created' | 'candidate.updated' | 'candidate.deleted' | 'offer.created' | 'offer.updated' | 'offer.approval.created' | 'offer.approval.approved' | 'offer.approval.rejected' | 'offer.approval.abandoned' | 'offer.approval.step.approved' | 'offer.approval.step.rejected' | 'offer.approver.skipped' | 'offer.approver.delegated' | 'offer.approval.comment.created' | 'job.approval.created' | 'job.approval.approved' | 'job.approval.rejected' | 'job.approval.abandoned' | 'job.approval.step.approved' | 'job.approval.step.rejected' | 'job.approver.skipped' | 'job.approver.delegated' | 'job.approval.comment.created' | 'review.created' | 'review.updated' | 'review.deleted' | 'application.screening-answers.created' | 'application.screening-answers.updated' | 'onboarding.process.started' | 'onboarding.assignments.high-priority.completed' | 'onboarding.assignments.completed' | 'onboarding.assignment.integration-relevant.completed' | 'onboarding.assignments.integration-relevant.completed' | 'interview.created' | 'interview.updated' | 'interview.canceled' | 'self-schedule.created' | 'winston.chat.visibility.changed'
    - `version` string
  - `status` 'inactive' | 'active'

## Other responses

- `400`: Invalid request query parameters.
- `403`: With codes: * **NO_PERMISSION_TO_MANAGE_WEBHOOKS** when no permission to manage webhook subscriptions * **SUBSCRIPTIONS_LIMIT_EXCEEDED** when subscription limit for subscriber is exceeded
- `422`: Incorrect subscription data. Provided callback URL is invalid or event name is 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)