Webhooks

Webhooks deliver real-time notifications

Get notified instantly when documents are processed, completed, or encounter errors.

Get started in 3 steps

1

Create your webhook endpoint

Set up an HTTPS endpoint that can receive POST requests with JSON payloads.

2

Configure in DocRouter

Go to Organization Settings → Webhooks, enable webhooks, enter your URL, and select events.

3

Test and verify

Click Test webhook to verify your endpoint receives events correctly.

What are Webhooks?

Webhooks are HTTP callbacks that notify your application when events occur in DocRouter. They enable real-time integrations without polling.

  • Real-time notifications: Get instant alerts when documents are processed
  • Event-driven workflows: Trigger actions in your systems automatically
  • Reliable delivery: Automatic retries with exponential backoff
  • Secure: HMAC signature verification for authentication

Event Types

DocRouter sends webhook notifications for these events:

  • document.uploaded — Document uploaded and ready for processing
  • llm.completed — LLM processing finished successfully
  • llm.error — LLM processing failed
  • document.error — Document processing failed
  • webhook.test — Test event sent when testing webhook configuration

Integration Guides

N8N Integration

Create a Webhook node in N8N, copy the URL, and paste it into DocRouter webhook settings. Select llm.completed to receive extracted data.

Use N8N nodes to send extracted JSON to your ERP, CRM, or database.

Temporal Workflows

For complex, long-running workflows, use Temporal signals to wait for the llm.completed webhook.

Once received, continue with validation, human-in-the-loop steps, or downstream integrations.

Authentication

DocRouter sends a cryptographic signature in the X-DocRouter-Signature header.

Verification (Node.js):

const crypto = require('crypto');

function verifySignature(secret, timestamp, body, signature) {
  const message = `${timestamp}.${body}`;
  const expected = crypto.createHmac('sha256', secret).update(message).digest('hex');
  return `sha256=${expected}` === signature;
}

Header Authentication

Send a static header value (compatible with N8N, Zapier, etc.).

Payload Format

All webhooks send JSON payloads:

{
  "event_id": "unique-event-id",
  "event_type": "document.uploaded",
  "timestamp": 1640995200,
  "organization_id": "your-org-id",
  "document": {
    "document_id": "doc-123",
    "document_name": "invoice.pdf",
    "tag_ids": ["tag1", "tag2"],
    "metadata": {}
  }
}

Best Practices

✓ Use HTTPS — Only use HTTPS endpoints for secure delivery.

✓ Verify Signatures — Always verify HMAC signatures to ensure authenticity.

✓ Check Timestamps — Reject requests older than 5 minutes to prevent replay attacks.

✓ Prevent Duplicates — Use event_id to prevent duplicate processing.

✓ Respond Quickly — Endpoints must respond within 10 seconds. Return HTTP 2xx for success.

Delivery & Retries

  • Timeout: Endpoints must respond within 10 seconds
  • Success: Return HTTP 2xx status codes
  • Retries: Failed deliveries retry up to 10 times with exponential backoff
  • Monitoring: View all deliveries in the webhook settings UI
  • Manual Retry: Click “Retry” on failed deliveries

Learn More

Ready to set up webhooks?

Open Dashboard