Webhooks
Learn how to receive events in your webhook endpoint
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 operation completion, file deletion, or any other event that may occur in the Scan Documents API.
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.deleted
event:
{
"data": {
"id": "file_y9f6oitmeoncvcou",
"name": "file-example",
"type": "image/png",
},
"id": "event_wal69rzpapqrm7yj",
"timestamp": "2025-04-12T15:55:19.000Z",
"type": "file.deleted"
}
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.
Webhooks vs Callback URLs
Scan Documents API in addition to webhooks, also supports callback URLs to receive notifications about task completion or failure.
Callback URLs are useful for simple use cases and integration with some automation tools, but they are not as flexible or powerful as webhooks.
Webhooks have several advantages over callback URLs:
- Event-Driven: Webhooks are event-driven, meaning they can notify you of various events in real-time, such as file uploads, deletions, or task completions. Callback URLs just return the task as it
was a
GET
request to the Get Task endpoint. - Multiple Events: Webhooks can deliver multiple types of events, while callback URLs are limited to task completion or failure notifications.
- Retry Mechanism: Webhooks have a built-in retry mechanism, while callback URLs do not.
- Security: Webhooks use HMAC signatures to verify the authenticity of the event, while callback URLs do not have this level of security.
- Custom Payloads: Webhooks can include a mechanism to transform payloads, while callback URLs do not have this feature.
- Event Filtering: Webhooks allow you to filter events by type, while callback URLs do not have this feature.
- Custom Headers: Webhooks allow you to include custom headers in the event, while callback URLs do not have this feature.
- Event History: Webhooks provide an event history, allowing you to see all events that have been delivered to your endpoint, while callback URLs do not have this feature.
If you don't need the advanced features of webhooks, you can use callback URLs for simple use cases. However, if you need more flexibility and control over the events you receive, webhooks are the way to go.