Webhooks
Integrate document extraction with your systems in real-time
TableFlow uses webhooks to push real-time notifications when document extractions are completed or updated. This allows your systems to automatically process extraction results without polling the API.
How Webhooks Work
Here’s how the extraction webhook flow works:
- A document is uploaded and processed by TableFlow
- TableFlow extracts data according to your template
- When processing completes, TableFlow sends a webhook notification to your endpoint
- Your system receives the webhook with extraction details
- You can then retrieve the full extraction data using the API
Webhooks contain metadata about the extraction. To retrieve the full extraction data including extracted fields and tables, use the API with the extraction ID from the webhook.
Configuring Webhooks
1. Create an Endpoint
First, create an endpoint in your application that can receive HTTP POST requests. This endpoint will receive the webhook payloads from TableFlow.
For testing, you can use Svix Play to quickly set up a temporary webhook endpoint.
2. Add the Endpoint to TableFlow
Navigate to your workspace settings in the TableFlow dashboard. Under the “Webhooks” section, add your endpoint URL and select the events you want to receive:
3. Send a Test Event
You can send a test event to verify your webhook setup:
You’ll be able to see the webhook receipt in your logs and in your endpoint system:
Webhook Events
TableFlow supports the following webhook events:
extraction.created
Sent when a new extraction is created but processing has not yet started.
extraction.processing
Sent when extraction processing has started.
extraction.completed
Sent when extraction processing has completed successfully.
extraction.failed
Sent when extraction processing has failed.
extraction.updated
Sent when extraction data has been manually updated through the UI or API.
Webhook Security
TableFlow signs all webhook requests with a signature in the svix-signature
header. You can use this signature to verify that the webhook is genuinely from TableFlow.
Transforming and Filtering Webhooks
You can transform webhook payloads or filter webhooks based on their content before they’re sent to your endpoint.
Enabling Transformations
To add a transformation, select “Enable” and “Edit transformation” under the “Advanced” tab of an endpoint:
Transform
You can modify the webhook payload to match your system’s requirements:
Filter
You can filter webhooks based on their content to only receive specific notifications:
Webhook Retries
If your endpoint returns a non-2xx status code, TableFlow will automatically retry the webhook delivery with exponential backoff:
- First retry: 5 minutes after the initial attempt
- Second retry: 30 minutes after the first retry
- Third retry: 2 hours after the second retry
- Fourth retry: 5 hours after the third retry
- Fifth retry: 10 hours after the fourth retry
After five failed attempts, the webhook will be marked as failed and will not be retried again.
Best Practices
- Respond Quickly - Your webhook endpoint should respond with a 2xx status code as quickly as possible
- Process Asynchronously - Handle the webhook processing in a background job or queue
- Verify Signatures - Always verify webhook signatures to ensure security
- Handle Duplicates - Design your webhook handler to be idempotent to handle potential duplicate deliveries
- Monitor Logs - Regularly check your webhook logs to identify and resolve any delivery issues
Next Steps
Learn how to set up Slack notifications to monitor your extractions in real-time.