Skip to content
Last updated

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

EventDescription
workflow.completedTriggered when a document workflow completes successfully.
workflow.failedTriggered when a document workflow ends in failure.
extract.completedTriggered when a document extraction finishes successfully.
extract.failedTriggered when a document extraction fails.

Webhook Payload Format

Each webhook POST request includes a JSON body like this:

{
  "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:

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.

Previous page