# Webhooks - Anesya

Webhooks allow your systems to receive real-time notifications when events occur within your Anesya workspace. This enables you to automate workflows, synchronize data, or trigger actions in your application whenever a document is processed.

{{ process.env.DASHBOARD_URL }}

## How It Works

When an event you're subscribed to occurs (e.g., a document extraction is completed), Anesya will send an HTTP `POST` request to the **Target URL** you defined.

* Webhooks are sent as JSON payloads.
* A webhook is considered successful if your server responds with a `2XX` HTTP status code (e.g. 200 OK).
* Any other status code is considered an error, and the delivery is logged as a **failed attempt**.
* You can **manually replay** any failed webhook attempt from your dashboard.


## Creating a Webhook

1. Navigate to **Settings → Webhooks**  in your Anesya dashboard.
2. Click **Create Webhook**.
3. Choose an **event type**.
4. Enter the **Target URL** (must be a valid `https://` endpoint).
5. Save.


You can create multiple webhooks for the same event, each with different target URLs.

## Event Types

| Event | Description |
|  --- | --- |
| `workflow.completed` | Triggered when a document workflow completes successfully. |
| `workflow.failed` | Triggered when a document workflow ends in failure. |
| `extract.completed` | Triggered when a document extraction finishes successfully. |
| `extract.failed` | Triggered when a document extraction fails. |


## Webhook Payload Format

Each webhook POST request includes a JSON body like this:


```json
{
  "id": "b1eaea1a-ee96-4f7d-a2cb-dbadff2da584", // ID of the webhook
  "event": "extract.completed", // Event type
  "timestamp": "2025-06-25T14:45:26Z", // Timestamp of the webhook
  "data": { // Extract Data
    "id": "dac926a0-d0f9-47f0-9678-bb9a562475af",
    "document_name": "invoice.pdf",
    "document_url": "/document/dac926a0-d0f9-47f0-9678-bb9a562475af/?type=extract",
    "content_images": [
      {
        "id": "863f5405-ad44-4b03-b88f-667d721ab120",
        "name": "_page_0_Picture_16.jpeg",
        "url": "/images/863f5405-ad44-4b03-b88f-667d721ab120/"
      }
    ],
    "server": "FR-1",
    "content": "Invoice content...",
    "extracted_data": {
      "Invoice number": {
        "name": "Invoice number",
        "content": "SFO0602FAC06611",
        "position": [
          [
            175.0,
            406.0,
            265.0,
            418.0,
            0
          ],
          [
            175.0,
            406.0,
            265.0,
            418.0,
            1
          ]
        ]
      }
    },
    "schema": "6c6ec37c-d103-4609-82e9-3cd4b8ccf32b",
    "workflow": null,
    "workflow_session_id": null,
    "status": "FINISHED",
    "error": null,
    "created_at": "2025-06-23T15:17:52.704355Z"
  } 
}
```

**Headers sent:**


```http
Content-Type: application/json
X-Webhook-Token: 61a95ee...
X-Webhook-Id: b1eaea1a-ee96-4f7d-a2cb-dbadff2da584
User-Agent: Anesya-WebhookBot/1.0
```

> 💡 Signature verification coming soon.


> URLs returned are relative to the Anesya platform.


## Handling Failures

* Your endpoint **must return a 2XX HTTP status** to confirm successful receipt.
* If not, the webhook is marked as **failed** and stored on your dashboard.
* You can **retry** any webhook manually from the dashboard.
* We recommend logging all incoming webhooks and responses on your end for traceability.


## Security Best Practices

* Each request includes a `X-Webhook-Token` header you can validate against your expected token.
* Signature-based HMAC verification will also be available soon.
* Avoid executing critical actions blindly—verify the payload first.
* Only expose webhook endpoints over `HTTPS`.


## Monitoring Webhooks

You can monitor each webhook’s delivery status directly in your dashboard:

* View the **history** of webhook calls.
* Inspect **payloads**, **headers**, **HTTP status**, and **response body**.
* See the **success/failure** state and any associated error messages.


## Need Help?

If you encounter issues with webhooks, contact us at [team@anesya.app](mailto:team@anesya.app).