---
title: "Create event subscription"
url: "https://docs.signnow.com/docs/basic-auth/operations/create-event-subscription"
type: "endpoint"
section: "basic-auth"
slug: "basic-auth/operations/create-event-subscription"
method: "POST"
path: "/api/v2/events"
operation_id: "create-event-subscription"
authorization: "bearer"
---

# Create event subscription

`POST /api/v2/events`

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.

This request works with both Basic and Bearer authorization.

For the request with Bearer authorization only, see [Create event subscription](/docs/manage-event-subscriptions/operations/create-event-subscription-2).

For more information, check out our video tutorial.

<details open>

**<summary>Video tutorial</summary>**

<sub><sup>Note: The design shown in the video is outdated, but the flow is still accurate. You can go ahead and follow the steps as demonstrated.</sup></sub>

[Video tutorial](https://www.youtube.com/watch?v=Knd_3VeqtJc)

</details>

## Authorization

bearer

## Request Body

**Schema**

```json
{
  "type": "object",
  "required": [
    "event",
    "entity_id",
    "action"
  ],
  "properties": {
    "event": {
      "type": "string",
      "description": "Event name that triggers the subscription. Check [list of events](/docs/guides-webhooks#entity-events)."
    },
    "action": {
      "type": "string",
      "description": "Action performed when the event occurs. Must be set to `callback`."
    },
    "entity_id": {
      "type": "string",
      "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",
          "description": "URL that receives the event callback."
        },
        "secret_key": {
          "type": "string",
          "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",
      "action": "callback",
      "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",
  "action": "callback",
  "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. No content.

**Example** (`Example 1`)

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

### 400

* `attributes` array is missing or empty.
* `callback` is missing.
* `action` is missing or its value differs from `callback`.
* `event` is missing or empty.
* `event` format is incorrect.
* `callback` format is incorrect.
* `callback` is not an URL.
* `integration_id` doesn't exist in database.
* Incorrect token.
* Event name is incorrect.
* `entity_id` is not 40 characters long.
* Callback validation failed.
* `integration_id` not a string.
* `docid_queryparam` not a boolean.
* `headers` not an array.
* `secret_key` not a string.
* `secret_key` is empty.
* `secret_key` exceeds 300 characters.
* `delete_access_token` not a boolean.
* `include_metadata` not a boolean.
* Extra properties in `json_attributes` array.
* `use_tls_12` (optional parameter) not a boolean.
* `delay` not an integer.
* `delay` is out of range.
* `retry_count` not an integer.
* `retry_count` out of range.


**Example** (`Example 1`)

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

**Example** (`Empty event`)

```json
{
  "code": 65582,
  "message": "event must not be empty"
}
```

**Example** (`Empty callback`)

```json
{
  "code": 400,
  "message": "callback must not be empty"
}
```

**Example** (`Incorrect host`)

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

**Example** (`Incorrect token`)

```json
{
  "code": 1537,
  "error": "invalid_token"
}
```

**Example** (`Empty attributes`)

```json
{
  "code": 400,
  "message": "attributes must not be empty"
}
```

**Example** (`Empty secret_key`)

```json
{
  "code": 400,
  "message": "secret_key must not be empty"
}
```

**Example** (`Extra properties`)

```json
{
  "code": 400,
  "message": "{{ name of extra parameter }} was not expected."
}
```

**Example** (`Incorrect action`)

```json
{
  "message": "Action must be equal 'callback'"
}
```

**Example** (`callback not url`)

```json
{
  "code": 400,
  "message": "callback must be url"
}
```

**Example** (`event not string`)

```json
{
  "code": 65582,
  "message": "event must be string"
}
```

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

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

**Example** (`headers not array`)

```json
{
  "code": 400,
  "message": "headers must be array"
}
```

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

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

**Example** (`Incorrect entity_id`)

```json
{
  "code": 400,
  "message": "entity_id must have 40 characters."
}
```

**Example** (`callback not string`)

```json
{
  "code": 65582,
  "message": "callback must be string"
}
```

**Example** (`Incorrect event name`)

```json
{
  "code": 400,
  "message": "Event does not exist"
}
```

**Example** (`secret_key not string`)

```json
{
  "code": 400,
  "message": "secret_key must be string"
}
```

**Example** (`use_tls_12 not boolean`)

```json
{
  "code": 400,
  "message": "use_tls_12 must be bool"
}
```

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

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

**Example** (`Incorrect integration_id`)

```json
{
  "message": "Invalid integration id - {integration_id}"
}
```

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

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

**Example** (`integration_id not string`)

```json
{
  "code": 400,
  "message": "integration_id must be string"
}
```

**Example** (`docid_queryparam not boolean`)

```json
{
  "code": 400,
  "message": "docid_queryparam must be bool"
}
```

**Example** (`include_metadata not boolean`)

```json
{
  "code": 400,
  "message": "include_metadata must be bool"
}
```

**Example** (`secret_key exceeds 300 chars`)

```json
{
  "code": 400,
  "message": "secret_key value is too long. It should have 300 character or less."
}
```

**Example** (`delete_access_token not boolean`)

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

### 401

Unauthorized

### 403

**Authorization =  bearer**

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


**Authorization =  basic**

* The request is sent by an application that is not within the allowed scope.

* The entity is not allowed for the user (the user is not the owner).

* A subscription for this event already exists.

**Example** (`Example 1`)

```json
{
  "message": "Subscription to event is not allowed"
}
```

**Example** (`application/json`)

```json
{
  "message": "Subscription to event is not allowed"
}
```

**Example** (`Subscription already exists`)

```json
{
  "errors": [
    {
      "message": "Event subscription already exists."
    }
  ]
}
```

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

```json
{
  "errors": [
    {
      "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** (`An entity from `entity_id` not found`)

```json
{
  "errors": [
    {
      "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/api/v2/events" \
  -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event": "document.complete", "action": "callback", "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/basic-auth/operations/create-event-subscription*