# 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.                      |