Get Started

# Webhooks - Anesya

Webhooks allow your systems to receive real-time notifications when parsing or extract events occur in your Anesya workspace.

## How It Works

When an event you subscribed to occurs, Anesya sends an HTTP `POST` request to the target URL you configured.

* Webhooks are sent as JSON payloads.
* A webhook delivery is considered successful if your server responds with a `2XX` HTTP status code.
* Any other status code is considered a failed delivery and is logged in your dashboard.
* You can manually replay a delivery from the dashboard.


## Creating a Webhook

1. Navigate to [Settings -> Webhooks](https://dashboard.anesya.app/webhook) in your Anesya dashboard.
2. Click **Create Webhook**.
3. Choose an event type.
4. Enter the target URL. It must use `https://`.
5. Save.


When a webhook is created, Anesya also generates a webhook secret. Store it securely and use it to verify webhook signatures on your side.

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

## Event Types

| Event | Description |
|  --- | --- |
| `parsing.in_queue` | Triggered when a parsing is queued. |
| `parsing.in_progress` | Triggered when a parsing starts processing. |
| `parsing.finished` | Triggered when a parsing completes successfully. |
| `parsing.partial_finished` | Triggered when a parsing completes but one or more pages failed. |
| `parsing.failed` | Triggered when a parsing fails. |
| `extract.completed` | Triggered when an extract completes successfully. |
| `extract.failed` | Triggered when an extract fails. |


## Webhook Payload Format

Each webhook request uses this top-level JSON shape:


```json
{
  "id": "b1eaea1a-ee96-4f7d-a2cb-dbadff2da584",
  "event": "extract.completed",
  "timestamp": "2026-04-22T10:15:26.123456+00:00",
  "data": {}
}
```

The `data` object depends on the event type.

### Extract payload example

For extract events, `data` contains the serialized extract resource:


```json
{
  "id": "b1eaea1a-ee96-4f7d-a2cb-dbadff2da584",
  "event": "extract.completed",
  "timestamp": "2026-04-22T10:15:26.123456+00:00",
  "data": {
    "id": "dac926a0-d0f9-47f0-9678-bb9a562475af",
    "document_name": "invoice.pdf",
    "parsing": "ca989d38-2ac0-4abe-82ff-fc46350309f5",
    "schema": "6c6ec37c-d103-4609-82e9-3cd4b8ccf32b",
    "status": "FINISHED",
    "result": {
      "invoice_number": "SFO0602FAC06611"
    },
    "error": null,
    "created_at": "2026-04-22T10:14:58.704355+00:00",
    "updated_at": "2026-04-22T10:15:26.104212+00:00"
  }
}
```

### Parsing payload example

For parsing events, `data` contains the serialized parsing resource:


```json
{
  "id": "b1eaea1a-ee96-4f7d-a2cb-dbadff2da584",
  "event": "parsing.finished",
  "timestamp": "2026-04-22T10:15:26.123456+00:00",
  "data": {
    "id": "6ea6f966-dacd-49fb-bbb6-112233445566",
    "document": {
      "id": "ef592bd9-25ea-448f-8809-b37124cc7bef",
      "filename": "invoice.pdf",
      "file_url": "/front/documents/ef592bd9-25ea-448f-8809-b37124cc7bef/download/",
      "metadata": {
        "source": "api"
      },
      "page_count": 2,
      "created_at": "2026-04-22T10:10:00+00:00",
      "updated_at": "2026-04-22T10:10:00+00:00"
    },
    "picture_description_enabled": false,
    "table_verification_enabled": false,
    "model": "PIGALLE",
    "pictures": [],
    "ocr_content": [],
    "markdown_content": "# Invoice",
    "pages_total": 2,
    "pages_success": 2,
    "pages_failed": 0,
    "status": "FINISHED",
    "metadata": {
      "source": "api"
    },
    "error": null,
    "created_at": "2026-04-22T10:10:02+00:00",
    "updated_at": "2026-04-22T10:10:20+00:00"
  }
}
```

## Headers Sent


```http
Content-Type: application/json
X-Anesya-Webhook-Id: b1eaea1a-ee96-4f7d-a2cb-dbadff2da584
X-Anesya-Webhook-Delivery-Id: 7f6f2b16-4e2f-4a2f-b01a-91cc06bc0b1b
X-Anesya-Webhook-Timestamp: 1776852926
X-Anesya-Webhook-Signature: v1=9a8f4d5b...
User-Agent: Anesya-WebhookBot/1.0
```

The signature is an HMAC SHA-256 over:


```text
delivery_id + "." + timestamp + "." + raw_request_body
```

Use the webhook secret returned at creation time to verify `X-Anesya-Webhook-Signature`.

## Handling Failures

* Your endpoint must return a `2XX` HTTP status to confirm successful receipt.
* Failed deliveries are stored in your dashboard with the response status and response body.
* You can manually replay a delivery from its webhook record.
* We recommend logging incoming deliveries on your side for traceability.


## Security Best Practices

* Verify `X-Anesya-Webhook-Signature` with your webhook secret before trusting the payload.
* Validate the timestamp and reject old deliveries if needed.
* Store `X-Anesya-Webhook-Delivery-Id` to make your consumer idempotent.
* Avoid executing critical actions blindly.
* Only expose webhook endpoints over `HTTPS`.


## Monitoring Webhooks

You can monitor webhook deliveries directly in your dashboard:

* view the delivery history
* inspect payloads, headers, response status, and response body
* check success or failure state
* replay a delivery from an existing webhook record


## Need Help?

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