> For the complete documentation index, see [llms.txt](https://support.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.docstudio.com/admin-panel/webhooks-callbacks/envelope-callbacks-overview/create-a-callback-api.md).

# Create a Callback (API)

Create a callback for a mailbox, including filters, retries, timeout, and success code settings.

To create a new callback record, use the following request:

| **Method** | ***Request URL\****           |
| ---------- | ----------------------------- |
| POST       | /api/v1/envelope/callback/add |

### **Create callback**

| **URL**       |                                                                                                                                |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Method        | POST                                                                                                                           |
| request URL   | /api/v1/envelope/callback/add                                                                                                  |
| **Headers**   |                                                                                                                                |
| content-type  | application/json                                                                                                               |
| authorization | Bearer {token}, where {token} is the authorization token that the user received after successful authorization on the platform |
| mailbox       | UUID of the mailbox to which you configured callbacks                                                                          |

### **REQUEST BODY**

```json
{
  "filter": {
      "label": ["string"],
      "status": ["COMPLETED"],
      "subject": "string",
      "receiveDateFrom": "2023-02-16T12:34:26.606Z",
      "receiveDateTo": "2023-02-16T12:34:26.606Z",
      "expireDateFrom": "2023-02-16T12:34:26.606Z",
      "expireDateTo": "2023-02-16T12:34:26.606Z",
      "template": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "sender": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "scope": ["inbox"]
  },
  "url": "string",
  "retries": 10,
  "timeout": 60000,
  "successCode": 200,
  "login": "string",
  "password": "string"
}
```

**Request body parameters are described below:**

<table data-header-hidden><thead><tr><th width="169"></th><th></th></tr></thead><tbody><tr><td>filter *</td><td>It is an object with a filter that determines which callbacks will be triggered. <code>It can be empty if you do not want to use any filters.</code></td></tr><tr><td>label</td><td>Filter envelopes by a label assigned to the envelope</td></tr><tr><td>status</td><td>Filter envelopes by status. Allowed statuses for callbacks are WAITING, COMPLETED, CANCELLED, EXPIRED (case insensitive)</td></tr><tr><td>subject</td><td>Filter envelopes by the respective subject of the envelope. The filter works according to the content rule. This means that if you apply a filter by subject <code>agreement</code>, all envelopes with the word <code>agreement</code> will be added to the callback queue, and a callback will be sent.</td></tr><tr><td>receiveDateFrom</td><td>Filter envelopes by receive date FROM the specified date and time</td></tr><tr><td>receiveDateTo</td><td>Filter envelopes by receive date TO the specified date and time</td></tr><tr><td>expireDateFrom</td><td>Filter envelopes by envelope expiration date FROM the specified date and time</td></tr><tr><td>expireDateTo</td><td>Filter envelopes by envelope expiration date TO the specified date and time</td></tr><tr><td>template</td><td>Filter envelopes by a specific template (the template from which the envelope was created). Allowed values are template UUIDs</td></tr><tr><td>sender</td><td>Filter envelopes by envelope sender. Allowed values are the sender's UUID</td></tr><tr><td>scope</td><td>Filter envelopes by direction of the email. Allowed values are inbox and outbox (case insensitive)</td></tr><tr><td>url *</td><td>The parameter defines the URL where the callback will be sent</td></tr><tr><td>retries *</td><td>The parameter defines the number of callback retry attempts. Retries may be applied if the URL is unreachable or if the success code received from the URL is different from the expected one. Allowed values are from 0 to 10. If <code>0</code> is set in the callback, the system tries to send the callback once and does not retry.</td></tr><tr><td>timeout *</td><td>The parameter defines a timeout in milliseconds for which the system waits for a response with a success code. If the timeout is reached, the retry procedure starts, if configured. Allowed values are from 100 to 60000.</td></tr><tr><td>successCode</td><td>The parameter defines the status code that the system expects for a successfully sent callback. If the status code received from the URL is different from the required one, the retry procedure is initiated, if configured. <code>If no value is set, the default value (Status code: 200) is applied.</code></td></tr><tr><td>login</td><td>The parameter defines the login for Basic auth <code>(if the URL is reachable only with Basic auth, this parameter has to be defined)</code></td></tr><tr><td>password</td><td>The parameter defines the password for Basic auth <code>(if the URL is reachable only with Basic auth, this parameter has to be defined)</code></td></tr></tbody></table>

\* - defines attribute as required

**RESPONSE**

In response, you get a `201` status code in case of successful callback creation and JSON data of the callback.

**Response example (JSON):**

```json
{
  "id": "f8c97405-9185-4998-a3c0-2c4d0edaf43b",
  "filter": {
      "label": ["string"],
      "status": ["COMPLETED"],
      "subject": "string",
      "receiveDateFrom": null,
      "receiveDateTo": null,
      "expireDateFrom": null,
      "expireDateTo": null,
      "template": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "sender": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "scope": ["inbox"]
  },
  "url": "string",
  "retries": 10,
  "timeout": 60000,
  "successCode": 200,
  "authType": "BASIC"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://support.docstudio.com/admin-panel/webhooks-callbacks/envelope-callbacks-overview/create-a-callback-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
