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

# Create event subscription

`POST /api/v2/events`

Allows to subscribe an external service(callback_url) to a specific event of user or document

## Authorization

bearer

## Request Body

**Schema**

```json
{
  "type": "object",
  "required": [
    "event",
    "entity_id"
  ],
  "properties": {
    "event": {
      "type": "string"
    },
    "action": {
      "type": "string"
    },
    "entity_id": {
      "type": "string"
    },
    "attributes": {
      "type": "object",
      "required": [
        "callback"
      ],
      "properties": {
        "headers": {
          "type": "object",
          "properties": {
            "int_head": {
              "type": "integer"
            },
            "bool_head": {
              "type": "boolean"
            },
            "float_head": {
              "type": "number"
            },
            "string_head": {
              "type": "string"
            }
          }
        },
        "callback": {
          "type": "string"
        },
        "use_tls_12": {
          "type": "boolean"
        },
        "integration_id": {
          "type": "string"
        },
        "docid_queryparam": {
          "type": "boolean"
        }
      }
    }
  }
}
```

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

```json
"\t\n{\n\"event\":\"document.open\",  //mandatory. Take event name from \"events\" database table\n\"entity_id\": \" \", //allowed values:\n\n//- User_unique_id - works only with events, the name of which starts from \"user.\" Ex: \"user.document.update\"\n\n//- Document_unique_id - works only with events, the name of which starts from \"document.\" Ex: \"document.open\"\n\"action\":\"callback\",\n\"attributes\": {\n\n\"callback\":\" \", //mandatory, //url of external callback url\n\"use_tls_12\" : true,  //not mandatory, If true - 1.2 tls version will be used. If false - default tls version will be used.\n\"integration_id\":\"Unique ID Integration System\",  //not mandatory, unique id of external system. It is stored in \"api_integrations\" database table\n\"docid_queryparam\": true, //if true - Json, which is sent callback will consist document id as query string parameter and as a part of \"callback_url\" parameter\n\n\"headers\":{ //not mandatory parameter. You can add any parameters to \"headers\" array\n\n\"string_head\":\"test\",\n\n\"int_head\":12,\n\n\"bool_head\":false,\n\n\"float_head\":12.24\n\n}\n\n}\n}"
```

## Responses

### 204

### 400

* "attributes must not be empty" - "attributes" array is missing or empty
* "'callback' is missing." -  required parameter "callback" is missing
* "Action must be equal 'callback'" - required parameter "action" is missing OR value of "action" parameter differs from 'callback'
* "event must not be empty" - required parameter "event" is missing or has an empty value
* "event must be string" - value of the "event" parameter is not a string
* "callback must be string" - value of the "callback" parameter is not a string
* "callback must be url" - value of "callback" parameter is not an URL
* "Invalid integration id - {integration_id}" - value of "integration_id" parameter doesn't exist in database

**Example** (`event`)

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

**Example** (`action`)

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

**Example** (`callback`)

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

**Example** (`attributes`)

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

**Example** (`empty event`)

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

**Example** (`integration`)

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

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

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

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

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

### 403

**Authorization =  bearer**

Request is sent with bearer token which doesn't belong user who is added to "entity_id" parameter

OR

Request is sent with bearer of user who is not an owner of document, added to "entity_id" parameter


**Authorization =  basic**

Correct request which is sent by application which is not in scope of allowed ones

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

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

## 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 '"\t\n{\n\"event\":\"document.open\",  //mandatory. Take event name from \"events\" database table\n\"entity_id\": \" \", //allowed values:\n\n//- User_unique_id - works only with events, the name of which starts from \"user.\" Ex: \"user.document.update\"\n\n//- Document_unique_id - works only with events, the name of which starts from \"document.\" Ex: \"document.open\"\n\"action\":\"callback\",\n\"attributes\": {\n\n\"callback\":\" \", //mandatory, //url of external callback url\n\"use_tls_12\" : true,  //not mandatory, If true - 1.2 tls version will be used. If false - default tls version will be used.\n\"integration_id\":\"Unique ID Integration System\",  //not mandatory, unique id of external system. It is stored in \"api_integrations\" database table\n\"docid_queryparam\": true, //if true - Json, which is sent callback will consist document id as query string parameter and as a part of \"callback_url\" parameter\n\n\"headers\":{ //not mandatory parameter. You can add any parameters to \"headers\" array\n\n\"string_head\":\"test\",\n\n\"int_head\":12,\n\n\"bool_head\":false,\n\n\"float_head\":12.24\n\n}\n\n}\n}"'
```

---
*Full reference: https://docs.signnow.com/docs/webhooks-1/operations/post__api_v2_events*