Overview
Retab uses HTTPS to send webhook events to your app as a JSON payload. When a workflow completes, the End (Webhook) node sends the processed data to your configured endpoint.Webhook Payload
The webhook sends a standardized JSON payload with the following structure:| Field | Type | Description |
|---|---|---|
document | MIMEData | null | Document data (if a file was passed to the End node) |
json | object | null | Extracted JSON data (if JSON was passed to the End node) |
MIMEData Structure
Thedocument field uses the MIMEData format:
| Field | Type | Description |
|---|---|---|
filename | string | Original filename (e.g., "invoice.pdf", "scan.png") |
url | string | Base64 data URL containing the file content |
url field is a data URL in the format:
Either
document or json (or both) will be present depending on what’s connected to the End node. If only an Extract node is connected, you’ll receive json with the extracted data. If a document is also passed through, you’ll receive both.Parsing the Payload
Setting Up Webhooks
To start receiving webhook events:- Create a webhook endpoint handler to receive POST requests
- Configure the End node in your workflow with your webhook URL
- Test your endpoint locally using the Retab SDK
- Secure your webhook endpoint with signature verification
Create a Webhook Endpoint Handler
Set up an HTTPS endpoint that:- Handles POST requests with a JSON payload
- Returns a successful status code (2xx) quickly before complex processing
- Validates the webhook signature for security
Configure the End Node
In your workflow:- Add an End (Webhook) node
- Connect your Extract or Functions node to the End node
- Configure the webhook URL and any custom headers
Test Your Webhook
Before deploying, test your webhook endpoint using the SDK:Securing Your Webhook
How Signature Verification Works
Retab uses HMAC-SHA256 to sign webhook payloads:- Signature Generation: Retab computes an HMAC-SHA256 signature of the payload using your webhook secret
- Signature Header: The signature is included in the
Retab-Signatureheader - Verification: Your server recomputes the signature and compares it to the header
Getting Your Webhook Secret
You can create a webhook security key directly from the End node in the workflow editor:- Click the key icon (🔑) in the End node header
- Click Create Security Key if you don’t have one
- Copy the generated secret
- Store it securely as an environment variable (e.g.,
WEBHOOKS_SECRET)
Implementation Examples
Security Best Practices
Always verify signatures
Always verify signatures
Never process webhook data without verifying the
Retab-Signature header. This prevents attackers from sending forged requests to your endpoint.Use HTTPS only
Use HTTPS only
Always use HTTPS endpoints for webhooks. HTTP endpoints expose your webhook data to interception.
Respond quickly
Respond quickly
Return a 2xx status code as soon as you receive and verify the webhook. Perform long-running processing asynchronously.
Handle retries
Handle retries
Retab may retry failed webhook deliveries. Implement idempotency to handle duplicate events gracefully.
Rotate secrets periodically
Rotate secrets periodically
Regularly rotate your webhook secret to minimize the impact of potential secret exposure.
Troubleshooting
Common Issues
| Issue | Solution |
|---|---|
| Missing signature header | Ensure you’re checking for Retab-Signature (case-insensitive) |
| Signature mismatch | Verify you’re using the raw request body, not parsed JSON |
| Timeout errors | Return 200 immediately, process data asynchronously |
| 404 errors | Check your webhook URL is accessible from the internet |
Debugging Tips
- Log incoming requests: Temporarily log the raw payload and headers to verify what you’re receiving
- Test locally: Use a tool like ngrok to expose your local server for testing
- Check dashboard: View webhook delivery logs in your Retab dashboard
- Verify secret: Ensure your
WEBHOOKS_SECRETmatches the one in your dashboard