# Webhook Management

Webhooks allow your application to automatically receive **real-time updates** when specific events occur in the Evia Sign platform — such as when a **signature request is sent**, or **completed**.

By configuring webhooks, you can eliminate the need for polling and seamlessly automate backend processes like notifications, updates, or workflows.

## Create a Webhook

This operation allows you to **create a webhook** in Evia Sign by submitting your callback URL and subscribing to specific event types. Once created, Evia Sign will send structured payloads to your URL every time a selected event is triggered.

## Request URL

<mark style="color:yellow;">`POST`</mark>`/api/v2/webhooks`

This is the request URL used to **create** and subscribe a new webhook.

{% hint style="info" %}
Your application must include the destination URL (`url`) and specify one or more event types (`events`) it wants to subscribe to.
{% endhint %}

### Required Headers

These headers are essential for authorizing the request and ensuring the server processes the payload correctly.

| Header        | Required | Description                                   |
| ------------- | -------- | --------------------------------------------- |
| Authorization | ✅ Yes    | Bearer token obtained from the OAuth 2.0 flow |
| Content-Type  | ✅ Yes    | Must be set to `application/json`             |

### Request Body Schema

The structure used to define your webhook’s behavior — including where the data should be sent and which events to listen for.

```json
{
  "url": "https://yourdomain.com/callback",
  "events": ["request.sent", "request.completed"]
}
```

This payload defines:

* The **public HTTPS** where Evia Sign will send updates.
* The **events** your system wants to subscribe to.

### Field Descriptions

Details about the fields expected in the request body — so developers understand what to send and why it matters.

| Field  | Type   | Required | Description                                                                      |
| ------ | ------ | -------- | -------------------------------------------------------------------------------- |
| url    | string | ✅ Yes    | Your HTTPS endpoint to receive event notifications. Must be publicly accessible. |
| events | array  | ✅ Yes    | List of event types to subscribe to (see supported events).                      |

### Supported Events

A list of available webhook event types that can be subscribed to. These determine what kinds of changes will trigger a callback to your server.

| Event Name          | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `request.sent`      | Triggered when a signature request has been received. |
| `request.completed` | Triggered when all required signatures are completed. |

### Example: Create a Webhook

A ready-to-use payload sample that shows how to submit a webhook creation request.

```json
{
  "url": "https://webhooks.yourdomain.com/evia-sign",
  "events": ["request.sent", "request.completed"]
}
```

### Event Payloads

Illustrates what your server will receive when each subscribed event occurs. Useful for developers to prepare their endpoint to handle incoming data correctly.

**`request.sent`**

```json
{
  "Name": "Jane Doe",
  "Email": "jane@example.com",
  "Subject": "Contract.pdf",
  "Link": "https://evia.enadocapp.com/sign/#/sign/abc123"
}
```

| Field   | Type   | Description                                    |
| ------- | ------ | ---------------------------------------------- |
| Name    | string | Name of the participant (initiator or signer). |
| Email   | string | Email address of the recipient.                |
| Subject | string | Title or filename of the document.             |
| Link    | string | Direct signing URL.                            |

***

**`request.completed`**

```json
{
  "RequestId": "abc123",
  "Status": "Completed"
}
```

| Field     | Type   | Description                                    |
| --------- | ------ | ---------------------------------------------- |
| RequestId | string | Unique ID of the completed signature request.  |
| Status    | string | Final status (`Completed`, `Cancelled`, etc.). |

### Delete a Webhook

Describes how to remove an existing webhook subscription when it’s no longer needed

**Request URL**

```
DELETE /api/v2/webhooks/webhookID
```

Replace `webhookId` with the actual ID of the webhook to be deleted.

### Possible Errors and How to Handle Them

A quick-reference table to help developers troubleshoot issues like malformed payloads, missing tokens, or duplicate registrations.

| Status Code | Error Message     | Explanation                                               |
| ----------- | ----------------- | --------------------------------------------------------- |
| 400         | Bad Request       | The request body is malformed or missing required fields. |
| 401         | Unauthorized      | Access token is missing or expired.                       |
| 404         | Webhook Not Found | The given webhook ID does not exist.                      |


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sign.enadocapp.com/evia-sign-api/v2/webhook-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.