## Webhooks

Manage webhooks for envelope events, at envelope level and at organization level.

> **Deprecation notice**
The `webhook-subscription` endpoints are **deprecated and will be removed on 31 October 2026**:
- `POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscription`
- `GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscription`
- `DELETE /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscription`

Migrate to the new `webhooks` endpoints described below before this date. After removal, calls to the old endpoints will fail. See [Migration from webhook-subscription](#migration-from-webhook-subscription).


Webhooks allow your application to receive real-time notifications about envelope events. Instead of polling the API for status updates, NSE pushes an event to your HTTPS endpoint as soon as the subscribed event occurs.

Webhooks can be registered at two levels:

| Level | Scope | Supported events |
|  --- | --- | --- |
| **Envelope** | A single envelope | All events (see [Supported events](#supported-events)) |
| **Organization** | All envelopes of the organization | `EnvelopeCompleted` only |


For both levels you register a webhook URL and select the event it should be triggered for (for example `EnvelopeCompleted` or `RecipientRejected`). Each webhook has its own `webhookId`, which you use to read, update, or delete it.

## Envelope webhooks

### List envelope webhooks

`GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks`

Returns all webhooks configured for the specified envelope.

#### Path Parameters

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `organizationId` | string (uuid) | Yes | Unique identifier of the organization |
| `envelopeId` | string (uuid) | Yes | Unique identifier of the envelope |


### Create envelope webhook

`POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks`

Creates a webhook for the specified envelope.

#### Path Parameters

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `organizationId` | string (uuid) | Yes | Unique identifier of the organization |
| `envelopeId` | string (uuid) | Yes | Unique identifier of the envelope |


#### Request Body

Content-Type: `application/json`

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `url` | string | Yes | The HTTPS URL to receive webhook events |
| `event` | `WebhookEventType` (string) | Yes | The event that triggers the webhook. See [Supported events](#supported-events) |
| `authentication` | `WebhookAuthenticationRequest` | No | Authentication settings for the webhook endpoint |


#### Supported events

| Event | Description |
|  --- | --- |
| `EnvelopeSent` | The envelope was sent |
| `EnvelopeCompleted` | The envelope was completed* |
| `EnvelopeCanceled` | The envelope was canceled |
| `EnvelopeRestarted` | The envelope was restarted |
| `EnvelopeDeleted` | The envelope was deleted |
| `RecipientCompleted` | A recipient completed their action |
| `RecipientRejected` | A recipient rejected the envelope |
| `RecipientDelegated` | A recipient delegated their action |


*With the feature **EnrichedWebhook** enabled the event **EnvelopeCompleted** returns additional data e.g. stages, recipients, artifacts and document class metadata.

#### WebhookAuthenticationRequest

| Field | Type | Nullable | Description |
|  --- | --- | --- | --- |
| `headers` | object (map<string, string>) | Yes | Optional HTTP headers to include in webhook calls, for example an `Authorization` header |
| `clientCertificate` | string | Yes | Optional PEM-encoded client certificate for mTLS |
| `clientKey` | string | Yes | Optional PEM-encoded private key for mTLS |


#### Example Request

```json
{
  "url": "https://example.com/hooks/envelope",
  "event": "EnvelopeCompleted",
  "authentication": {
    "headers": {
      "Authorization": "Bearer token_123"
    }
  }
}
```

#### Example Payload - envelope completed (without enriched webhook feature)

```json
{
  "type": "EnvelopeCompleted",
  "id": "cf02da82-1234-1234-1234-f07c9fafb1d0",
  "occurredAt": "2026-11-17T08:12:17.767+00:00",
  "organizationId": "afa1c381-1234-1234-1234-6e6796af7ff3",
  "envelope": {
    "id": "6af2128b-1234-1234-1234-881581c104c3",
    "status": "Completed"
  }
}
```

#### Example Payload - envelope completed (with enriched webhook feature)

```json
{
  "type": "EnvelopeCompleted",
  "id": "7d84ac88-1234-1234-1234-faae948cfe07",
  "occurredAt": "2026-11-17T08:16:44.947+00:00",
  "organizationId": "afa1c381-1234-1234-1234-6e6796af7ff3",
  "envelope": {
    "id": "f2c3c35d-1234-1234-1234-2a882bca7e19",
    "status": "Completed",
    "name": "Contract for Mario Rossi",
    "createdAt": "2026-11-17T08:15:49.637+00:00",
    "sentAt": "2026-11-17T08:16:18.976+00:00",
    "completedAt": "2026-11-17T08:16:42.701+00:00",
    "stages": [
      {
        "id": "5d501c26-1234-1234-1234-cdcdc5918d52",
        "name": "Stage3",
        "sortOrder": 1,
        "type": "Signer",
        "requiredRecipientCompletions": 1,
        "recipients": [
          {
            "id": "d92c57ca-1234-1234-1234-3931cc784a6e",
            "givenName": "Mario",
            "surname": "Rossi",
            "email": "m.gierlinger@namirial.com",
            "status": "Completed",
            "completedAt": "2026-11-17T08:16:42.374+00:00"
          }
        ]
      },
      {
        "id": "dc1ab1b6-1234-1234-1234-3ed51f23904e",
        "name": "",
        "sortOrder": 2,
        "type": "CarbonCopy",
        "requiredRecipientCompletions": 0,
        "recipients": [
          {
            "id": "d0965a53-1234-1234-1234-c88fc3db7f86",
            "givenName": "Mario",
            "surname": "Rossi",
            "email": "m.rossi@sample.com",
            "status": "Completed",
            "completedAt": "2026-11-17T08:16:42.701+00:00"
          }
        ]
      }
    ],
    "artifacts": [
      {
        "id": "cfe314d5-1234-1234-1234-24c974923fe5",
        "type": "CompletedFile",
        "name": "A.pdf",
        "fileId": "662806f3-1234-1234-1234-539c12ef097c",
        "downloadLink": {
          "url": "https://"
        }
      },
      {
        "id": "314676fd-1234-1234-1234-edfec12150ba",
        "type": "AuditTrail",
        "name": "Audit Trail.pdf",
        "downloadLink": {
          "url": "https://"
        }
      }
    ]
  }
}
```

### Get envelope webhook

`GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}`

Returns the specified webhook.

#### Path Parameters

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `organizationId` | string (uuid) | Yes | Unique identifier of the organization |
| `envelopeId` | string (uuid) | Yes | Unique identifier of the envelope |
| `webhookId` | string (uuid) | Yes | Unique identifier of the webhook |


### Update envelope webhook

`PUT /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}`

Updates the specified webhook. The request body (`UpdateEnvelopeWebhookRequest`) has the same structure as for [Create envelope webhook](#create-envelope-webhook): `url` and `event` are required, `authentication` is optional.

#### Path Parameters

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `organizationId` | string (uuid) | Yes | Unique identifier of the organization |
| `envelopeId` | string (uuid) | Yes | Unique identifier of the envelope |
| `webhookId` | string (uuid) | Yes | Unique identifier of the webhook |


#### Example Request

```json
{
  "url": "https://example.com/hooks/envelope-new",
  "event": "EnvelopeCompleted",
  "authentication": {
    "headers": {
      "Authorization": "Bearer token_123"
    }
  }
}
```

### Delete envelope webhook

`DELETE /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}`

Deletes the specified webhook.

#### Path Parameters

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `organizationId` | string (uuid) | Yes | Unique identifier of the organization |
| `envelopeId` | string (uuid) | Yes | Unique identifier of the envelope |
| `webhookId` | string (uuid) | Yes | Unique identifier of the webhook |


## Organization webhooks

Organization webhooks are triggered for the matching event on **all envelopes** of the organization, so you don't need to register a webhook for each envelope.

> **Note**
Organization webhooks only support the `EnvelopeCompleted` event. Envelope webhooks support every event listed in [Supported events](#supported-events).


The request and payload structures are the same as for envelope webhooks. See [WebhookAuthenticationRequest](#webhookauthenticationrequest) and the [example payloads](#example-payload---envelope-completed-without-enriched-webhook-feature) above. The **EnrichedWebhook** feature also applies to organization webhooks.

### List organization webhooks

`GET /api/v1/organizations/{organizationId}/webhooks`

Returns all webhooks configured for the specified organization.

#### Path Parameters

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `organizationId` | string (uuid) | Yes | Unique identifier of the organization |


### Create organization webhook

`POST /api/v1/organizations/{organizationId}/webhooks`

Creates a new webhook for the specified organization. Only the `EnvelopeCompleted` event is supported.

#### Path Parameters

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `organizationId` | string (uuid) | Yes | Unique identifier of the organization |


#### Request Body

Content-Type: `application/json`

Request body (`CreateOrganizationWebhookRequest`) for creating an organization webhook.

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `url` | string | Yes | The HTTPS URL to receive webhook events |
| `event` | `WebhookEventType` (string) | Yes | The event that triggers the webhook. For organization webhooks only `EnvelopeCompleted` is supported |
| `authentication` | `WebhookAuthenticationRequest` | No | Authentication settings for the webhook endpoint |


#### Example Request

```json
{
  "url": "https://example.com/hooks/organization",
  "event": "EnvelopeCompleted",
  "authentication": {
    "headers": {
      "Authorization": "Bearer token_123"
    }
  }
}
```

### Get organization webhook

`GET /api/v1/organizations/{organizationId}/webhooks/{webhookId}`

Returns the specified organization webhook.

#### Path Parameters

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `organizationId` | string (uuid) | Yes | Unique identifier of the organization |
| `webhookId` | string (uuid) | Yes | Unique identifier of the webhook |


### Update organization webhook

`PUT /api/v1/organizations/{organizationId}/webhooks/{webhookId}`

Updates the specified organization webhook. The request body has the same structure as for [Create organization webhook](#create-organization-webhook): `url` and `event` are required, `authentication` is optional.

#### Path Parameters

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `organizationId` | string (uuid) | Yes | Unique identifier of the organization |
| `webhookId` | string (uuid) | Yes | Unique identifier of the webhook |


#### Example Request

```json
{
  "url": "https://example.com/hooks/organization-new",
  "event": "EnvelopeCompleted",
  "authentication": {
    "headers": {
      "Authorization": "Bearer token_123"
    }
  }
}
```

### Delete organization webhook

`DELETE /api/v1/organizations/{organizationId}/webhooks/{webhookId}`

Deletes the specified organization webhook.

#### Path Parameters

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `organizationId` | string (uuid) | Yes | Unique identifier of the organization |
| `webhookId` | string (uuid) | Yes | Unique identifier of the webhook |


### Migration from webhook-subscription

The old `webhook-subscription` endpoints are deprecated and will be removed on **31 October 2026**. To migrate:

| Deprecated endpoint | Replacement |
|  --- | --- |
| `POST .../envelopes/{envelopeId}/webhook-subscription` | `POST .../envelopes/{envelopeId}/webhooks` (the `event` field is now required) |
| `GET .../envelopes/{envelopeId}/webhook-subscription` | `GET .../envelopes/{envelopeId}/webhooks` or `GET .../envelopes/{envelopeId}/webhooks/{webhookId}` |
| `DELETE .../envelopes/{envelopeId}/webhook-subscription` | `DELETE .../envelopes/{envelopeId}/webhooks/{webhookId}` |


Changes to be aware of:

- Requests now require the `event` field.
- Webhooks are identified by a `webhookId`, which is needed to get, update, or delete a single webhook.
- Webhooks can now be updated with `PUT`, without deleting and recreating them.