> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/guides/envelope-callbacks.md).

# Envelope callbacks

This document contains the endpoint reference for creating and managing envelope callbacks.

### Create callback

| Method | Endpoint                        |
| ------ | ------------------------------- |
| `POST` | `/api/v1/envelope/callback/add` |

Headers:

<table><thead><tr><th width="152.6666259765625">Header</th><th width="134.5555419921875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Yes</td><td>Bearer authorization token</td></tr><tr><td><code>Content-Type</code></td><td>Yes</td><td>Use <code>application/json</code></td></tr><tr><td><code>Mailbox</code></td><td>Yes</td><td>Mailbox context header with the current mailbox UUID</td></tr></tbody></table>

Request body:

```json
{
  "url": "string",
  "retries": 3,
  "timeout": 5000,
  "successCode": 200,
  "login": "string",
  "password": "string",
  "filter": {
    "label": [
      "string"
    ],
    "status": [
      "DRAFT"
    ],
    "subject": "string",
    "createDateFrom": "2026-07-21T15:58:42.779Z",
    "createDateTo": "2026-07-21T15:58:42.779Z",
    "receiveDateFrom": "2026-07-21T15:58:42.779Z",
    "receiveDateTo": "2026-07-21T15:58:42.779Z",
    "expireDateFrom": "2026-07-21T15:58:42.779Z",
    "expireDateTo": "2026-07-21T15:58:42.779Z",
    "sendDateFrom": "2026-07-21T15:58:42.779Z",
    "sendDateTo": "2026-07-21T15:58:42.779Z",
    "template": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "templateVersion": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "sender": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "form": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "metadata": {
      "externalId": "CRM-1024"
    }
  }
}
```

Request body fields:

<table><thead><tr><th width="132">Field</th><th width="90.333251953125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>url</code></td><td>string</td><td>Callback URL</td></tr><tr><td><code>retries</code></td><td>integer</td><td>Number of callback retry attempts, default: <code>3</code>, maximum: <code>10</code></td></tr><tr><td><code>timeout</code></td><td>integer</td><td>Request timeout in milliseconds, default: <code>5000</code></td></tr><tr><td><code>successCode</code></td><td>integer</td><td>HTTP response code that DocStudio treats as successful, default: <code>200</code></td></tr><tr><td><code>login</code></td><td>string</td><td>Login for Basic authentication, when the callback URL requires it</td></tr><tr><td><code>password</code></td><td>string</td><td>Password for Basic authentication, when the callback URL requires it</td></tr><tr><td><code>filter</code></td><td>object</td><td>Envelope filter that defines which envelopes trigger the callback</td></tr></tbody></table>

The request body is required. The Swagger schema does not mark individual body fields as required.

### Filter fields

Use the `filter` object to limit when the callback is sent. For envelope form callbacks, use the `form` array and pass one or more form UUIDs. If the callback must trigger only for completed envelopes created from a specific form, combine `form` with `status: ["COMPLETED"]`.

<table><thead><tr><th width="179">Field</th><th width="165.111083984375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>label</code></td><td>array of strings</td><td>Label UUID or name</td></tr><tr><td><code>status</code></td><td>array of strings</td><td>Envelope status; supported values: <code>DRAFT</code>, <code>SENT</code>, <code>WAITING</code>, <code>COMPLETED</code>, <code>CANCELLED</code>, <code>EXPIRED</code>, <code>ON_APPROVAL</code></td></tr><tr><td><code>subject</code></td><td>string</td><td>Envelope subject</td></tr><tr><td><code>createDateFrom</code></td><td>date-time</td><td>Creation date from</td></tr><tr><td><code>createDateTo</code></td><td>date-time</td><td>Creation date to</td></tr><tr><td><code>receiveDateFrom</code></td><td>date-time</td><td>Receive date from</td></tr><tr><td><code>receiveDateTo</code></td><td>date-time</td><td>Receive date to</td></tr><tr><td><code>expireDateFrom</code></td><td>date-time</td><td>Expiration date from</td></tr><tr><td><code>expireDateTo</code></td><td>date-time</td><td>Expiration date to</td></tr><tr><td><code>sendDateFrom</code></td><td>date-time</td><td>Envelope sending date from</td></tr><tr><td><code>sendDateTo</code></td><td>date-time</td><td>Envelope sending date to</td></tr><tr><td><code>template</code></td><td>array of UUIDs</td><td>Template IDs</td></tr><tr><td><code>templateVersion</code></td><td>array of UUIDs</td><td>Template version IDs</td></tr><tr><td><code>sender</code></td><td>array of UUIDs</td><td>Sender mailbox IDs</td></tr><tr><td><code>form</code></td><td>array of UUIDs</td><td>Form IDs, used to target envelopes created from selected forms</td></tr><tr><td><code>metadata</code></td><td>object</td><td>Metadata key-value pairs used as callback filter criteria</td></tr></tbody></table>

### Create callback for a form

Use this structure when the callback must be sent only for envelopes created from a specific envelope form. Replace `{formUuid}` with the actual form UUID and set the required target status for your integration.

```json
{
  "url": "https://example.com/docstudio/callback",
  "retries": 3,
  "timeout": 5000,
  "successCode": 200,
  "filter": {
    "status": [
      "COMPLETED"
    ],
    "form": [
      "{formUuid}"
    ]
  }
}
```

This callback matches envelopes created from the selected form with the `COMPLETED` status.

### Create callback response

The endpoint returns `201 Created` with the created callback configuration. Save the returned `id`; it is the callback UUID used by callback management endpoints.

```json
{
  "url": "string",
  "retries": 3,
  "timeout": 5000,
  "successCode": 200,
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "authType": "NONE",
  "filter": {
    "label": [
      "string"
    ],
    "status": [
      "DRAFT"
    ],
    "subject": "string",
    "createDateFrom": "2026-07-21T15:58:42.780Z",
    "createDateTo": "2026-07-21T15:58:42.780Z",
    "receiveDateFrom": "2026-07-21T15:58:42.780Z",
    "receiveDateTo": "2026-07-21T15:58:42.780Z",
    "expireDateFrom": "2026-07-21T15:58:42.780Z",
    "expireDateTo": "2026-07-21T15:58:42.780Z",
    "sendDateFrom": "2026-07-21T15:58:42.780Z",
    "sendDateTo": "2026-07-21T15:58:42.780Z",
    "template": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "templateVersion": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "sender": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "form": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "metadata": {
      "externalId": "CRM-1024"
    }
  }
}
```

Response fields:

<table><thead><tr><th width="178.66650390625">Field</th><th width="143.4444580078125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>url</code></td><td>string</td><td>Callback URL</td></tr><tr><td><code>retries</code></td><td>integer</td><td>Number of retry attempts</td></tr><tr><td><code>timeout</code></td><td>integer</td><td>Request timeout in milliseconds</td></tr><tr><td><code>successCode</code></td><td>integer</td><td>HTTP response code treated as successful</td></tr><tr><td><code>id</code></td><td>UUID</td><td>Envelope callback ID</td></tr><tr><td><code>authType</code></td><td>string</td><td>Authentication type; supported values: <code>NONE</code>, <code>BASIC</code></td></tr><tr><td><code>filter</code></td><td>object</td><td>Envelope filter used by the callback</td></tr></tbody></table>

### Status codes

| Code | Description                   |
| ---- | ----------------------------- |
| 201  | Callback created successfully |

### List callbacks

| Method | Endpoint                         |
| ------ | -------------------------------- |
| `GET`  | `/api/v1/envelope/callback/list` |

Headers:

<table><thead><tr><th width="150.111083984375">Header</th><th width="158">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Yes</td><td>Bearer authorization token</td></tr><tr><td><code>Mailbox</code></td><td>Yes</td><td>Mailbox context header with the current mailbox UUID</td></tr></tbody></table>

The response is an array of callback objects in the [create callback response](#create-callback-response) format.

### Status codes

| Code | Description                     |
| ---- | ------------------------------- |
| 200  | Callbacks returned successfully |

### Callback payload example

<table><thead><tr><th width="298.4444580078125">Method</th><th>Endpoint</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/api/v1/envelope/callback/callbackRequestPayload</code></td></tr></tbody></table>

Response:

```json
{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "DRAFT",
  "subject": "string",
  "label": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "receiveDate": "2026-07-21T16:00:22.093Z",
  "expireDate": "2026-07-21T16:00:22.093Z",
  "template": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sender": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "mailbox": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

Payload fields:

| Field         | Type           | Description              |
| ------------- | -------------- | ------------------------ |
| `uuid`        | UUID           | Envelope UUID            |
| `status`      | string         | Envelope status          |
| `subject`     | string         | Envelope subject         |
| `label`       | array of UUIDs | Envelope labels          |
| `receiveDate` | date-time      | Envelope receive date    |
| `expireDate`  | date-time      | Envelope expiration date |
| `template`    | UUID           | Template UUID            |
| `sender`      | UUID           | Sender mailbox UUID      |
| `mailbox`     | UUID           | Current mailbox UUID     |

### Status codes

| Code | Description                       |
| ---- | --------------------------------- |
| 200  | Callback payload example returned |

{% hint style="warning" %}
Make sure the envelope matches the callback filter. Return the configured `successCode` before the configured `timeout`.
{% endhint %}

### Related topics

* [Metadata](/guides/envelope-metadata.md)
* [Check Envelope Status](/api-reference/check-envelope-status.md)
* [Working with XML payloads](/guides/xml-payloads.md)