Overview#
Docpier's webhook system provides real-time notifications about document processing events, allowing your applications to stay synchronized with document extraction workflows. Webhooks are sent via HTTP POST requests to your configured endpoints when specific events occur during document processing.Event Types#
Docpier webhooks support the following event types:| Event | Description | Trigger |
|---|
PROCESSING_FINALISED | Document processing workflow completed successfully | All processing phases finished successfully |
PROCESSING_FAILED | Document processing failed | Error in any processing phase |
FEEDBACK_RECEIVED | User feedback submitted for document | Feedback endpoint called |
Webhook Payload Schema#
All webhook payloads follow this consistent structure:{
"event": "PROCESSING_FINALISED",
"occurred": "2025-01-15T10:30:45.123Z",
"status": "COMPLETED",
"message": "Document processing completed successfully",
"details": {
"workspaceId": "01HXYZ123456789ABCDEF",
"documentId": "01HXYZ987654321FEDCBA",
"filename": "invoice_2025.pdf",
"fileSize": 245760,
"fileHash": "sha256:abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
"extRef": "INV-2025-001",
"uploadSource": "API"
},
"webhookId": "01HXYZ456789123ABCDEF",
"retryCount": 0
}
Field Descriptions#
| Field | Type | Required | Description |
|---|
event | string | Yes | Event type from the event enum |
occurred | string (ISO 8601) | Yes | Timestamp when event occurred |
status | string | No | Current processing status |
message | string | No | Human-readable message describing the event |
metadata | object | Yes | Document metadata and processing information |
webhookId | string (ULID) | Yes | Unique webhook delivery identifier |
retryCount | integer | Yes | Current retry attempt (0 for first delivery) |
Details Fields#
| Field | Type | Description |
|---|
workspaceId | string (ULID) | Yes |
documentId | string (ULID) | Yes |
filename | string | Original uploaded filename |
fileSize | integer | File size in bytes |
fileHash | string | SHA-256 hash of the document file |
extRef | string | External reference provided during upload |
uploadSource | string | Source of upload: "API" or "UPLOAD" |
Authentication#
Docpier supports three authentication methods for webhook endpoints:1. No Authentication#
2. Basic Authentication#
3. Bearer Token (OAuth2.0)#
Delivery Policy#
Retry Strategy#
Maximum Retries: 10 attempts
Retry Interval: Exponential backoff
Total Retry Window: 24 hours
Webhook Timeout: 10 seconds per attempt
Success Criteria#
HTTP status code 2xx (200-299)
Response received within 10 seconds
Failure Handling#
Non-2xx status codes trigger retries
Network timeouts trigger retries
Connection failures trigger retries
After 10 failed attempts, webhook is marked as permanently failed
Idempotency#
Each webhook delivery has a unique webhookId
Include webhookId in your database to prevent duplicate processing
Webhooks may be delivered multiple times due to retries
Security Considerations#
TLS Requirements#
Production: HTTPS endpoints required
Development: HTTP endpoints allowed for testing
Minimum TLS Version: TLS 1.2
IP Whitelisting (Optional, but recommended)#
Configure your firewall to only accept connections from Docpier's IP ranges
Contact support for current IP address ranges
This is a security recommendation, not a requirement
Configuration#
Webhook Endpoint Registration#
Webhook endpoints are configured manually by the Docpier team (webhook management endpoints are going to be provided soon). To set up webhooks for your workspace, please provide the following information:Webhook URL: The HTTPS endpoint where webhooks should be sent
Authentication Type: none, basic, or bearer
Authentication Credentials:For Basic Auth: username and password
For Bearer Token: client ID and client secret
For OAuth2.0: additional auth URL if needed
Workspace ID: Your unique workspace identifier
Subject: "Webhook Configuration Request - [Workspace ID]"
Include: All required information listed above
Configuration Process#
1.
Send configuration request to support
2.
Docpier team validates your endpoint
3.
Configuration is applied to your workspace
4.
Test webhook is sent to verify setup
5.
Webhooks become active for your workspace
Integration Examples#
Basic Webhook Handler (Node.js)#
Testing & Development#
Webhook Testing#
1.
Test Endpoint: Contact support to request a test webhook
2.
Local Development: Use tools like ngrok to expose local endpoints
3.
Payload Validation: Verify your handler processes all required fields
ngrok Setup for Local Testing#
Webhook Logs#
Webhook delivery logs are not accessible by partners
Contact support to check webhook delivery status
Support can verify retry attempts and final delivery status
Troubleshooting#
Common Issues#
Webhook Not Receiving Events#
Verify endpoint URL is accessible from external networks
Check authentication credentials
Ensure endpoint returns 2xx status codes
Verify firewall/network configuration
Contact support to verify webhook configuration
Duplicate Webhooks#
Implement idempotency using webhookId
Check for multiple webhook configurations
Verify retry logic isn't causing duplicates
Authentication Failures#
Verify client credentials
Ensure correct authentication method
Contact support for credential verification
Endpoint Not Reachable#
Verify HTTPS endpoint is publicly accessible
Check SSL certificate validity
Ensure no firewall blocking incoming connections
Test endpoint with simple HTTP client
Best Practices#
1. Idempotency#
2. Error Handling#
Process webhooks asynchronously when possible
Use database transactions for data consistency
Implement proper logging and monitoring
Handle webhooks quickly to avoid timeouts
4. Security#
Monitor for suspicious activity
Keep authentication credentials secure
5. Monitoring#
Track success/failure rates
Set up alerts for webhook failures
Monitor endpoint availability
Modified at 2025-08-12 15:39:26
