What are Webhooks?
Webhooks are user-defined HTTP callbacks that are triggered by specific events in the Ademero platform. When an event occurs—such as a document being created, a workflow completing, or data extraction finishing—the webhook automatically sends real-time data to your specified endpoint. This eliminates the need for constant polling and enables true event-driven architecture for your integrations.
Instead of repeatedly asking "Did anything happen?" through API polling, webhooks notify your application immediately when something important occurs. This approach is more efficient, reduces latency, and enables real-time processing of business events.
Key Benefits of Using Webhooks
- •Real-time Integration: Get instant notifications when events happen, enabling immediate response and processing
- •Reduced Server Load: Eliminate constant polling requests that consume bandwidth and server resources
- •Lower Latency: Process events as they happen rather than waiting for scheduled checks
- •Automatic Retries: Failed deliveries are automatically retried with exponential backoff
- •Cryptographic Verification: Each webhook includes a signature to verify it came from Ademero
- •Scalable Architecture: Handle millions of events without API rate limiting concerns
How Webhooks Work
Get notified instantly when events occur in your Ademero account
1. Event Occurs
An action happens in Ademero (document uploaded, workflow completed, etc.)
2. Webhook Triggered
Ademero generates a webhook event with relevant data
3. HTTP POST
Event data is sent to your webhook endpoint via secure HTTPS
4. Process Event
Your application processes the event and takes action
Available Webhook Events
Subscribe to the events that matter to your integration
Security Best Practices
Keep your webhook integrations secure and reliable
Verify Webhook Signatures
Always validate the signature to ensure the webhook came from Ademero
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}Use HTTPS Endpoints
Always use HTTPS URLs for your webhook endpoints
// Good
https://api.yourcompany.com/webhooks/ademero
// Bad
http://api.yourcompany.com/webhooks/ademeroImplement Idempotency
Handle duplicate events gracefully using the event ID
// Store processed event IDs
const processedEvents = new Set();
function handleWebhook(event) {
if (processedEvents.has(event.id)) {
return { status: 'already_processed' };
}
// Process the event
processEvent(event);
processedEvents.add(event.id);
return { status: 'processed' };
}Return Quickly
Acknowledge receipt quickly and process asynchronously
app.post('/webhook', (req, res) => {
// Acknowledge immediately
res.status(200).send('OK');
// Process asynchronously
processQueue.add({
event: req.body,
headers: req.headers
});
});Managing Webhooks
Create, monitor, and troubleshoot your webhook endpoints
Your Webhook Endpoints
https://api.example.com/webhooks/ademeroACTIVEhttps://automation.company.com/hooks/documentsACTIVEhttps://legacy.system.com/webhookERRORCreating a Webhook
// Using the JavaScript SDK
const webhook = await client.webhooks.create({
url: 'https://api.example.com/webhooks',
events: [
'document.created',
'document.updated',
'workflow.completed'
],
secret: 'your-webhook-secret',
active: true
});
console.log('Webhook created:', webhook.id);Handling Webhook Events
// Express.js webhook handler
app.post('/webhooks/ademero', (req, res) => {
const signature = req.headers['x-ademero-signature'];
const payload = JSON.stringify(req.body);
if (!verifySignature(payload, signature)) {
return res.status(401).send('Invalid signature');
}
const event = req.body;
switch (event.event) {
case 'document.created':
handleDocumentCreated(event.data);
break;
case 'workflow.completed':
handleWorkflowCompleted(event.data);
break;
}
res.status(200).send('OK');
});Advanced Webhook Configuration
Event Filtering and Subscriptions
You can configure your webhooks to listen only to specific events that matter for your use case. The Ademero webhook system supports fine-grained event filtering, allowing you to optimize delivery and reduce unnecessary processing. Instead of receiving all events, you can subscribe to only the events your integration needs to handle.
For example, a document archiving system might only care about "document.deleted" events, while an accounting integration might focus on "extraction.completed" events for invoice processing. This reduces bandwidth usage and keeps your webhook queue focused.
Webhook Signature and Headers
Every webhook sent from Ademero includes cryptographic headers to verify its authenticity. The platform includes the following security-related headers in each request:
X-Ademero-Signature: <HMAC-SHA256 signature>
X-Ademero-Timestamp: <Unix timestamp>
X-Ademero-Event-ID: <Unique event identifier>
Always verify the signature using your webhook secret. This ensures the webhook came from Ademero and hasn't been tampered with in transit.
Retry Logic and Delivery Guarantees
Ademero implements a robust retry mechanism to ensure delivery of critical events. When a webhook delivery fails, the system automatically retries with exponential backoff spacing. This helps handle transient failures in your infrastructure.
The complete retry schedule is:
- Immediate delivery attempt
- First retry after 1 minute
- Second retry after 5 minutes
- Third retry after 30 minutes
- Fourth retry after 2 hours
- Fifth retry after 12 hours
- Final retry after 24 hours
If all retries fail, the webhook is marked as permanently failed and you can investigate using the webhook logs dashboard. Events that fail delivery are retained for 30 days.
Webhook Rate Limits
Ademero webhooks are designed to scale without traditional rate limits. Your webhook endpoint can receive thousands of events per second without triggering rate limit errors. However, your endpoint should still be able to handle the incoming traffic efficiently.
If your endpoint is unable to keep up with incoming webhooks, consider implementing queue-based processing or requesting a delayed delivery schedule for non-critical events.
Real-World Webhook Use Cases
Invoice Processing Automation
Subscribe to "extraction.completed" events to automatically process invoice data. When the AI extraction finishes, your integration receives the extracted fields (invoice number, amount, vendor details) and can immediately send them to your accounting system or ERP.
Benefits: Eliminate manual data entry, reduce processing time from days to seconds, prevent duplicate invoices
Document Archival and Backup
Use "document.created" webhooks to automatically archive documents to cold storage, backup services, or third-party systems. Each new document triggers a webhook that can initiate backup procedures.
Benefits: Automatic compliance with data retention policies, reduced storage costs, distributed redundancy
Workflow Notifications and Escalations
Subscribe to workflow completion and failure events to send real-time notifications to relevant team members. When a "workflow.failed" event occurs, automatically escalate to managers or create incident tickets.
Benefits: Faster issue resolution, improved SLAs, proactive alert management
Slack/Teams Notifications
Send webhook events to Slack or Microsoft Teams channels to keep teams updated on important document and workflow events. Create formatted messages with links to documents and relevant context.
Benefits: Improved team collaboration, centralized notifications, reduced email clutter
Workflow Integration with External Systems
Trigger actions in external systems when workflows complete successfully. For example, create Jira tickets from workflow outputs, send data to CRM systems, or trigger downstream processes in business applications.
Benefits: Seamless system integration, eliminated manual handoffs, improved data flow
Troubleshooting & FAQs
Common issues and how to resolve them
Webhook delivery failures
If your webhook endpoint returns an error or times out, Ademero will retry the delivery with exponential backoff.
- • First retry: 1 minute
- • Second retry: 5 minutes
- • Third retry: 30 minutes
- • Fourth retry: 2 hours
- • Fifth retry: 12 hours
Testing webhooks locally
Use tools like ngrok or localtunnel to expose your local development server to the internet for webhook testing.
Webhook timeout
Your webhook endpoint must respond within 10 seconds. For long-running processes, acknowledge the webhook immediately and process asynchronously.
Can I receive webhooks on multiple endpoints?
Yes! You can create multiple webhook endpoints, each subscribing to different events. This allows you to route different events to different systems. For example, one endpoint for document events and another for workflow events.
How do I handle duplicate webhook deliveries?
Although Ademero aims for exactly-once delivery, network issues can occasionally cause duplicates. Implement idempotency by storing the event ID and checking if you've already processed that event. The event ID is included in both the request body and the X-Ademero-Event-ID header.
What is the maximum webhook payload size?
Webhook payloads are limited to 1MB in size. For most events, the payload is significantly smaller (typically 1-10KB). If you need to transmit larger amounts of data, include URLs in the webhook payload and fetch additional details via API calls.
How can I test webhooks in development?
Use tunneling services like ngrok, localtunnel, or Cloudflare Tunnel to expose your local development server. For example:
This gives you a public URL that forwards requests to your local machine. Use this URL when creating test webhook endpoints.
Can I disable a webhook temporarily?
Yes! Each webhook endpoint has an active/inactive status. You can deactivate a webhook through the dashboard or API without deleting it. This is useful for maintenance windows or temporarily pausing integrations.
How long are webhook logs retained?
Webhook delivery logs are retained for 30 days. You can view delivery status, response codes, and error messages in the webhook logs dashboard during this period. For permanent records, implement your own logging in your webhook handler.
What happens if I change my webhook secret?
Changing the webhook secret will invalidate all previous signatures. Use the new secret to verify incoming webhooks. Make sure to update your verification code before rotating the secret, or temporarily disable signature verification during the transition.
Can I filter webhooks by specific document properties?
Currently, event filtering is available at the event type level (e.g., subscribe to all "document.created" events). Implement additional filtering logic in your webhook handler to filter by specific document properties, tags, or custom metadata.
Webhook Best Practices
Guidelines for reliable webhook integrations
Verify Signatures
Always validate the X-Ademero-Signature header to ensure webhook authenticity. This prevents unauthorized requests and potential security vulnerabilities in your integration. Use HMAC SHA-256 for cryptographic verification.
Implement Idempotency
Use event IDs to track processed webhooks and prevent duplicate processing during retries. Store event IDs in your database and skip events that have already been handled. This ensures data consistency.
Respond Quickly
Return HTTP 200 within 10 seconds to acknowledge receipt. Queue long-running tasks for asynchronous processing. Immediate responses prevent timeout errors and unnecessary retry attempts from our servers.
Monitor Webhook Health
Track delivery rates, response times, and error patterns. Set up alerts for failing endpoints. Regular monitoring helps identify issues before they impact your integration reliability or user experience.