---
title: "Create event subscription"
url: "https://docs.signnow.com/docs/manage-event-subscriptions/operations/create-event-subscription-2"
type: "endpoint"
section: "manage-event-subscriptions"
slug: "manage-event-subscriptions/operations/create-event-subscription-2"
method: "POST"
path: "/v2/event-subscriptions"
operation_id: "create-event-subscription-2"
authorization: "bearer"
---

# Create event subscription

`POST /v2/event-subscriptions`

This endpoint allows 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.


## Authorization

bearer

## Request Body

**Schema**

```json
{
  "type": "object",
  "required": [
    "event",
    "entity_id"
  ],
  "properties": {
    "event": {
      "type": "string",
      "example": "document.open",
      "description": "Event name that triggers the subscription. Check [list of events](/docs/guides-webhooks#entity-events)."
    },
    "entity_id": {
      "type": "string",
      "example": "a1b2c3d4e5f67890123456789abcdef012345678",
      "description": "Unique string ID of the entity (e.g., `document_id`, `user_id`, `document_group_id`)."
    },
    "attributes": {
      "type": "object",
      "required": [
        "callback"
      ],
      "properties": {
        "delay": {
          "type": "integer",
          "default": 0,
          "maximum": 100,
          "minimum": 0,
          "description": "Delay in seconds before the webhook is sent after the event triggers."
        },
        "headers": {
          "type": "object",
          "properties": {
            "int_head": {
              "type": "integer",
              "description": "Example integer header."
            },
            "bool_head": {
              "type": "boolean",
              "description": "Example boolean header."
            },
            "float_head": {
              "type": "number",
              "description": "Example float header."
            },
            "string_head": {
              "type": "string",
              "description": "Example string header."
            }
          },
          "description": "Custom HTTP headers to be sent with the callback request (e.g., Authorization tokens)."
        },
        "callback": {
          "type": "string",
          "example": "https://webhook.site/a0093533-766c-456e-b625-97592745216a",
          "description": "URL that receives the event callback."
        },
        "secret_key": {
          "type": "string",
          "example": "c8XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "maxLength": 300,
          "description": "Secret key used to generate the HMAC signature for verifying request authenticity."
        },
        "use_tls_12": {
          "type": "boolean",
          "description": "Whether TLS 1.2 should be used for the callback request."
        },
        "retry_count": {
          "type": "integer",
          "maximum": 10,
          "minimum": 1,
          "multipleOf": 10,
          "description": "Maximum number of retries if the webhook fails with a 5xx error."
        },
        "integration_id": {
          "type": "string",
          "description": "Optional unique ID to identify the external system integration."
        },
        "docid_queryparam": {
          "type": "boolean",
          "description": "Whether the document ID is included as a query parameter in the callback URL."
        },
        "include_metadata": {
          "type": "boolean",
          "description": "Whether document metadata is included in the callback payload."
        },
        "delete_access_token": {
          "type": "boolean",
          "default": true,
          "description": "If `true`, the access token is removed from the webhook payload for security. Default is `true`."
        }
      },
      "description": "Configuration for the webhook callback."
    }
  },
  "x-examples": {
    "Example 1": {
      "event": "document.complete",
      "entity_id": "document_id",
      "attributes": {
        "headers": {
          "int_head": 12,
          "bool_head": false,
          "float_head": 12.24,
          "string_head": "sample_text"
        },
        "callback": "https://webhook.site/a0093533-766c-456e-b625-97592745216a",
        "use_tls_12": true,
        "integration_id": "Unique ID Integration System",
        "docid_queryparam": true
      },
      "secret_key": "c8XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
  }
}
```

**Example** (`Example 1`)

```json
{
  "event": "document.complete",
  "entity_id": "document_id",
  "attributes": {
    "delay": 50,
    "headers": {
      "int_head": 12,
      "bool_head": false,
      "float_head": 12.24,
      "string_head": "sample_text"
    },
    "callback": "https://webhook.site/a0093533-766c-456e-b625-97592745216a",
    "secret_key": "c8XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "use_tls_12": true,
    "retry_count": 3,
    "integration_id": "Unique ID Integration System",
    "docid_queryparam": true
  }
}
```

## Responses

### 201

Event subscription created.

**Example** (`Example 1`)

```json
{
  "data": {
    "id": "XXXXXXXXaa59418f996b81deb701697aa403fa72"
  }
}
```

### 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 invalid 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 invalid.
* `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 invalid.
* `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.

**Example** (`Example 1`)

```json
{
  "errors": [
    {
      "code": 15007018,
      "message": "The `attributes.callback` field must not be empty."
    }
  ]
}
```

**Example** (`Limit reached`)

```json
{
  "errors": [
    {
      "code": 15006044,
      "message": "Active subscriptions are limited to 20 subscriptions with this combination of entityId and eventName."
    }
  ]
}
```

**Example** (`Event is empty`)

```json
{
  "errors": [
    {
      "code": 15007010,
      "message": "The `event` field must not be empty."
    }
  ]
}
```

**Example** (`Callback is empty`)

```json
{
  "errors": [
    {
      "code": 15007018,
      "message": "The `attributes.callback` field must not be empty."
    }
  ]
}
```

**Example** (`delay not integer`)

```json
{
  "errors": [
    {
      "code": 15007034,
      "message": "The `attributes.delay` field must be an integer."
    }
  ]
}
```

**Example** (`Entity_id is empty`)

```json
{
  "errors": [
    {
      "code": 15007013,
      "message": "The `entity_id` field must not be empty."
    }
  ]
}
```

**Example** (`delay out of range`)

```json
{
  "errors": [
    {
      "code": 15007035,
      "message": "The `attributes.delay` field must be between 0 and 100."
    }
  ]
}
```

**Example** (`Attributes is empty`)

```json
{
  "errors": [
    {
      "code": 15007016,
      "message": "The `attributes` field must not be empty."
    }
  ]
}
```

**Example** (`Callback is missing`)

```json
{
  "errors": [
    {
      "code": 15007028,
      "message": "The \"callback\" field is missing."
    }
  ]
}
```

**Example** (`Secret_key is empty`)

```json
{
  "errors": [
    {
      "code": 15007025,
      "message": "The `attributes.secret_key` must not be empty."
    }
  ]
}
```

**Example** (`Event does not exist`)

```json
{
  "errors": [
    {
      "code": 15007011,
      "message": "Provided event does not exist."
    }
  ]
}
```

**Example** (`Payload is incorrect`)

```json
{
  "code": 65536,
  "message": "Invalid payload"
}
```

**Example** (`retry_count not integer`)

```json
{
  "errors": [
    {
      "code": 15007031,
      "message": "The `attributes.retry_count` field must be an integer."
    }
  ]
}
```

**Example** (`API subscription expired`)

```json
{
  "errors": [
    {
      "code": 80001002,
      "message": "Your API subscription could not be found."
    }
  ]
}
```

**Example** (`retry_count out of range`)

```json
{
  "errors": [
    {
      "code": 15007032,
      "message": "The `attributes.retry_count` field must be between 1 and 10."
    }
  ]
}
```

**Example** (`Callback host unreachable`)

```json
{
  "errors": [
    {
      "code": 15007029,
      "message": "Unknown callback host or callback host unreachable."
    }
  ]
}
```

**Example** (`Integration_id is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007032,
      "message": "Invalid integration id - {integration_id}"
    }
  ]
}
```

**Example** (`Callback host is not allowed`)

```json
{
  "errors": [
    {
      "code": 15006001,
      "message": "Host is not allowed."
    }
  ]
}
```

**Example** (`Entity_id length is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007014,
      "message": "The `entity_id` field must have 40 characters."
    }
  ]
}
```

**Example** (`Callback format is invalid URL`)

```json
{
  "errors": [
    {
      "code": 15007019,
      "message": "The `attributes.callback` field must be url."
    }
  ]
}
```

**Example** (`Event format type is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007009,
      "message": "The `event` field must be string."
    }
  ]
}
```

**Example** (`Secret_key length is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007026,
      "message": "The `secret_key` value is too long. It should have 300 character or less."
    }
  ]
}
```

**Example** (`Headers format type is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007023,
      "message": "The `attributes.headers` field must be array."
    }
  ]
}
```

**Example** (`Callback format type is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007017,
      "message": "The `attributes.callback` field must be string."
    }
  ]
}
```

**Example** (`Duplicate subscription combination`)

```json
{
  "errors": [
    {
      "code": 15006045,
      "message": "Active subscriptions must have different combinations of entityId, eventName, and callbackUrl."
    }
  ]
}
```

**Example** (`Entity_id format type is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007012,
      "message": "The `entity_id` field must be string."
    }
  ]
}
```

**Example** (`Integration_id length is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007031,
      "message": "The `integration_id` field must have 40 characters."
    }
  ]
}
```

**Example** (`Attributes format type is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007015,
      "message": "The `attributes` field must be array."
    }
  ]
}
```

**Example** (`Secret_key format type is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007024,
      "message": "The `attributes.secret_key` must be string."
    }
  ]
}
```

**Example** (`Use_tls_12 format type is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007020,
      "message": "The `attributes.use_tls_12` field must be bool."
    }
  ]
}
```

**Example** (`Integration_id format type is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007021,
      "message": "The `attributes.integration_id` field must be string."
    }
  ]
}
```

**Example** (`Docid_queryparam format type is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007022,
      "message": "The `attributes.docid_queryparam` field must be bool."
    }
  ]
}
```

**Example** (`Include_metadata format type is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007030,
      "message": "The `attributes.include_metadata` field must be bool."
    }
  ]
}
```

**Example** (`Delete_access_token format type is incorrect`)

```json
{
  "errors": [
    {
      "code": 15007027,
      "message": "The `attributes.delete_access_token` field must be bool."
    }
  ]
}
```

### 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.


**Example** (`Example 1`)

```json
{
  "errors": [
    {
      "code": 80001003,
      "message": "Your API subscription is inactive."
    }
  ]
}
```

**Example** (`Limit reached`)

```json
{
  "errors": [
    {
      "code": 80001006,
      "message": "You have reached the limit of event subscriptions."
    }
  ]
}
```

**Example** (`Subscription expired`)

```json
{
  "errors": [
    {
      "code": 80001005,
      "message": "Your API subscription has expired."
    }
  ]
}
```

**Example** (`Subscription inactive`)

```json
{
  "errors": [
    {
      "code": 80001003,
      "message": "Your API subscription is inactive."
    }
  ]
}
```

**Example** (`Subscription not allowed for user (not an owner)`)

```json
{
  "errors": [
    {
      "code": 15006009,
      "message": "Subscription to event is not allowed"
    }
  ]
}
```

### 404

* `entity_id` not found.

**Example** (`Example 1`)

```json
{
  "errors": [
    {
      "message": "Not found entity with id = {entity_id}"
    }
  ]
}
```

**Example** (`Entity_id not found`)

```json
{
  "errors": [
    {
      "code": 15006005,
      "message": "Not found entity with id = {entity_id}"
    }
  ]
}
```

## Code Examples

> Replace `$SIGNNOW_ACCESS_TOKEN` and any `{placeholder}` values before running.

### cURL

```bash
curl -X POST \
  "https://api.signnow.com/v2/event-subscriptions" \
  -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event": "document.complete", "entity_id": "document_id", "attributes": {"delay": 50, "headers": {"int_head": 12, "bool_head": false, "float_head": 12.24, "string_head": "sample_text"}, "callback": "https://webhook.site/a0093533-766c-456e-b625-97592745216a", "secret_key": "c8XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "use_tls_12": true, "retry_count": 3, "integration_id": "Unique ID Integration System", "docid_queryparam": true}}'
```

---
*Full reference: https://docs.signnow.com/docs/manage-event-subscriptions/operations/create-event-subscription-2*