Webhooks

Overview

Use webhooks to receive real-time events from your Scan Documents API activity, so your backend can respond to these events and act accordingly.

Receiving webhook events is useful for handling asynchronous events such as when a recipient signs an envelope, an envelope is completed, a deliverable is generated, or an email to a recipient bounces.

Setting Up Webhooks

You can receive events by registering a webhook endpoint in the Dashboard. You can register different webhook endpoints and select the specific events to subscribe to for each endpoint.

Events

When an event happens, Scan Documents creates a new Event object. This event triggers a webhook notification if user has registered a webhook endpoint and subscribed to the event type.

This is an example of an event object for a file.created event:

{
    "data": {
      "object_id": "file_y9f6oitmeoncvcou",
      "object_type": "file"
    },
    "id": "event_wal69rzpapqrm7yj",
    "timestamp": "2025-04-12T15:55:19.000Z",
    "type": "file.created"
}

Learn more about the different types of events.

Event Delivery

Scan Documents API delivers the event via a POST request to your webhook endpoint, with the Event object as the JSON payload.

Delivery is successful if your endpoint responds with a status code in the 2XX range (200 to 299). Any other status code means the delivery failed. In order to prevent timeouts, please ensure your endpoint responds within 5 seconds. If your endpoint takes longer than that, try to enqueue the event for processing and respond with a 202 Accepted status code.

Scan Documents API does not guarantee the order of event delivery, so your endpoint should be able to handle events arriving out of order.

Retries

If your endpoint responds with a status code outside the 2XX range, Scan Documents API will keep trying to deliver the event for up to 48 hours, using an exponential backoff strategy.

Authentication

Webhook notifications are secured with an HMAC signature included in the svix-signature header.

You can find the Signing Secret in the right column of the webhook endpoint definition:

You can check how to verify the signature of the webhook in the Svix documentation.

Tools

These tools can be useful for testing webhooks:

• Webhook.site: Generates a random endpoint URL and lets you inspect POST requests sent to that endpoint.
• ngrok: Sets up a tunnel from an internet-facing endpoint to your local machine, allowing you to process webhooks locally.
• Cloudflare: Sets up a tunnel from an internet-facing endpoint to your local machine, allowing you to process webhooks locally.