---
title: "Edit event subscription"
url: "https://docs.signnow.com/docs/manage-event-subscriptions/operations/put-v2-event-subscriptions-subscription_id"
type: "endpoint"
section: "manage-event-subscriptions"
slug: "manage-event-subscriptions/operations/put-v2-event-subscriptions-subscription_id"
method: "PUT"
path: "/v2/event-subscriptions/{subscription_id}"
operation_id: "put-v2-event-subscriptions-subscription_id"
authorization: "bearer"
---

# Edit event subscription

`PUT /v2/event-subscriptions/{subscription_id}`

This endpoint allows users to update an existing event subscription.

## Authorization

bearer

## Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `subscription_id` | string | Yes | ID of the subscription. Must match the pattern: [a-z0-9]{40}. |

## Header Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Content-Type` | string | No | application/json |

## Request Body

**Schema**

```json
{
  "type": "object",
  "required": [
    "event",
    "entity_id",
    "attributes"
  ],
  "properties": {
    "event": {
      "type": "string",
      "example": "document.open",
      "description": "Event that should trigger the subscription."
    },
    "action": {
      "type": "string",
      "example": "callback",
      "description": "Always only \"callback\""
    },
    "entity_id": {
      "type": "string",
      "example": "2e1fa467c4674e988a0542de8bf2f22cb0498410",
      "maxLength": 40,
      "minLength": 40,
      "description": "ID of the entity that should trigger the subscription."
    },
    "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"
            }
          },
          "description": "You can add any parameters to the \"headers\" array."
        },
        "callback": {
          "type": "string",
          "example": "https://webhook.site/a0093533-766c-456e-b625-97592745216a",
          "description": "URL that should receive the callback."
        },
        "secret_key": {
          "type": "string",
          "maxLength": 300,
          "description": "Enables the HMAC security logic."
        },
        "use_tls_12": {
          "type": "boolean",
          "description": "If true, the 1.2 TLS version will be used. If false, the default TLS version will be used. "
        },
        "integration_id": {
          "type": "string",
          "description": "External system ID"
        },
        "docid_queryparam": {
          "type": "boolean",
          "description": "If true, a JSON that is sent in a callback will contain document ID as a query string parameter and as a part of \"callback_url\" parameter."
        },
        "include_metadata": {
          "type": "boolean",
          "description": "Whether the payload of the webhook should include metadata."
        },
        "delete_access_token": {
          "type": "boolean",
          "default": false,
          "description": "Determines whether to keep access_token in the payload. If true, an access_token key id removed from the payload. If false, the access_token is kept in the payload attributes."
        }
      }
    }
  }
}
```

## Responses

### 204

Success, no content

### 400

* Incorrect Bearer token
* `event` is not a string
* `event` is empty
* `event` doesn't exist
* `entity_id` is not a string
* `entity_id` is missing
* `entity_id` is not 40 characters long
* `attributes` is not an array
* `attributes` is empty
* `attributes` error
* `callback` is not a string
* `callback` is empty
* `callback` is missing
* `callback` is not a valid email address
* `callback` URL is not allowed
* `callback` host unknown or unreachable
* `use_tls_12` is not a boolean
* `integration_id` is not a string
* `integration_id` is not 40 characters long
* Incorrect `integration_id`
* `docid_queryparam` is not a boolean
* `headers` is not an array
* `secret_key` is not a string
* `secret_key` is empty
* `secret_key` is longer than 300 characters
* `delete_access_token` is not a boolean
* `include_metadata` is not a boolean

**Example** (`Empty event`)

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

**Example** (`callback empty`)

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

**Example** (`Attributes error`)

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

**Example** (`Empty attributes`)

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

**Example** (`Empty secret_key`)

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

**Example** (`callback missing`)

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

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

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

**Example** (`include_metadata`)

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

**Example** (`entity_id missing`)

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

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

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

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

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

**Example** (`event doesn't exist`)

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

**Example** (`secret_key too long`)

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

**Example** (`attributes not array`)

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

**Example** (`entity_id not string`)

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

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

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

**Example** (`Incorrect Bearer token`)

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

**Example** (`entity_id length error`)

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

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

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

**Example** (`Incorrect integration_id`)

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

**Example** (`callback URL not allowed`)

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

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

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

**Example** (`integration_id length error`)

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

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

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

**Example** (`callback not an email address`)

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

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

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

**Example** (`callback host unknown or unreachable`)

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

### 403

* The bearer token is valid but it belongs to another user.
* Subscription update is not allowed.
* API subscription is not found.
* API subscription is inactive.
* API subscription has expired.

**Example** (`Token of another user`)

```json
{
  "errors": [
    {
      "code": 15006004,
      "message": "Event subscription is not allowed."
    }
  ]
}
```

**Example** (`Expired API subscription`)

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

**Example** (`Inactive API subscription`)

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

**Example** (`API subscription not found`)

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

**Example** (`Subscription update not allowed`)

```json
{
  "errors": [
    {
      "code": 15006010,
      "message": "Updating of subscription to event is not allowed"
    }
  ]
}
```

### 404

* The entity ID doesn't exist.
* The subscription ID doesn't exist.

**Example** (`Entity ID not found`)

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

**Example** (`Subscription ID not found`)

```json
{
  "errors": [
    {
      "code": 15006003,
      "message": "Event subscription not found."
    }
  ]
}
```

## Code Examples

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

### cURL

```bash
curl -X PUT \
  "https://api.signnow.com/v2/event-subscriptions/{subscription_id}" \
  -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

---
*Full reference: https://docs.signnow.com/docs/manage-event-subscriptions/operations/put-v2-event-subscriptions-subscription_id*