---
title: "Create event subscription"
method: POST
path: "/v2/event-subscriptions"
---

# Create event subscription

`POST /v2/event-subscriptions`

## Request

- Base URL: `https://api.signnow.com`
- URL: `https://api.signnow.com/v2/event-subscriptions`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/signnow/apis/signnow-api/docs/v2/event-subscriptions/post.ts> (a function with typed inputs; its response is checked against the schema)

This endpoint allows API users to subscribe an external service (`callback_url`) to a specific event related to a user, document, or document group. When the subscribed event occurs, your service receives a notification.

See the full list of available events in the [Webhooks user guide](/docs/guides-webhooks#entity-events).
Use [HMAC verification](/docs/guides-webhooks#hmac-security) for an additional layer of security.

> [!NOTE]
> For the payload your service receives for each event, see the response examples in [Get callback info by ID](/docs/callbacks-info/operations/get-v2-dashboard-event-subscriptions-subscription-id-callbacks).

## Request body

- object
  - `event` string, required: Event name that triggers the subscription. Check [list of events](/docs/guides-webhooks#entity-events).
  - `entity_id` string, required: Unique string ID of the entity (e.g., `document_id`, `user_id`, `document_group_id`).
  - `attributes` object: Configuration for the webhook callback.
    - `delay` integer: Delay in seconds before the webhook is sent after the event triggers.
    - `headers` object: Custom HTTP headers to be sent with the callback request (e.g., Authorization tokens).
      - `int_head` integer: Example integer header.
      - `bool_head` boolean: Example boolean header.
      - `float_head` number: Example float header.
      - `string_head` string: Example string header.
    - `callback` string, required: URL that receives the event callback.
    - `secret_key` string: Secret key used to generate the HMAC signature for verifying request authenticity.
    - `use_tls_12` boolean: Whether TLS 1.2 should be used for the callback request.
    - `retry_count` integer: Maximum number of retries if the webhook fails with a 5xx error.
    - `integration_id` string: Optional unique ID to identify the external system integration.
    - `docid_queryparam` boolean: Whether the document ID is included as a query parameter in the callback URL.
    - `include_metadata` boolean: Whether document metadata is included in the callback payload.
    - `delete_access_token` boolean: If `true`, the access token is removed from the webhook payload for security. Default is `true`.

## Response `201`

Event subscription created.

- object
  - `data` object: Created event subscription.
    - `id` string: ID of the event subscription.

## Other responses

- `400`: * `event` format type is incorrect. * `event` is empty. * `event` does not exist. * `entity_id` format type is incorrect. * `entity_id` is empty. * `entity_id` length is incorrect. * `attributes` format type is incorrect. * `attributes` is empty. * `callback` is missing. * `callback` format type is incorrect. * `callback` is empty. * `callback` format is wrong URL. * `callback` host is not allowed. * `callback` host unreachable. * `use_tls_12` format type is incorrect. * `integration_id` format type is incorrect. * `integration_id` length is incorrect. * `integration_id` is wrong. * `docid_queryparam` format type is incorrect. * `headers` format type is incorrect. * `secret_key` format type is incorrect. * `secret_key` is empty. * `secret_key` length is incorrect. * `delete_access_token` format type is incorrect. * `include_metadata` format type is incorrect. * Payload is wrong. * `delay` not integer. * `delay` out of range. * `retry_count` not integer. * `retry_count` out of range. * Subscription limit reached. * This combination of `entity_id`, `event`, and `callback_url` has already been used. * API subscription not found.
- `403`: * The request is sent with a bearer token that does not belong to the user specified in the `entity_id` parameter. * The request is sent with a bearer token of a user who is not the owner of the document specified in the `entity_id` parameter. * API subscription is inactive. * API subscription has expired. * User reached the limit of event subscriptions.
- `404`: * `entity_id` not found.

---

[API](https://skmtc.dev/signnow/apis/signnow-api.md) - [All operations](https://skmtc.dev/signnow/apis/signnow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signnow/apis/signnow-api/revisions/1c9c30a6142b?raw)