🔔Webhook Fundamentals

Learn how to set up and use webhooks with Docs-Dispatcher for real-time event notifications.

What are Webhooks?

Webhooks are HTTP callbacks that notify your application when events occur in Docs-Dispatcher. Instead of polling for status updates, your application receives automatic notifications when:

Documents are signed
Mail is delivered
Invoices are created
Errors occur

Benefits

Real-time notifications:

Instant updates without polling
Reduced API calls and latency
Better user experience

Automated workflows:

Trigger actions based on events
Update databases automatically
Send notifications to users

Async operation support:

Handle long-running operations
Scale without blocking
Retry failed operations

Supported Services

Service

Webhooks Supported

Providers

eSign

✅ Yes

Universign, Signaturit

Postal

✅ Yes

MySendingBox

Invoicing

❌ No

N/A

Email

❌ No

N/A

SMS

❌ No

N/A

File

❌ No

N/A

Upload

❌ No

N/A

👉 See all webhook events

How Webhooks Work

┌──────────────┐                      ┌──────────────┐
│ Your App     │                      │ Dispatcher   │
│              │  1. Dispatch Request │              │
│              │─────────────────────>│              │
│              │                      │              │
│              │  2. Queued Response  │              │
│              │<─────────────────────│              │
└──────────────┘                      └──────┬───────┘
       ↑                                     │
       │                                     │ 3. Process
       │                                     │
       │                              ┌──────▼───────┐
       │                              │ Provider     │
       │                              │ (Universign) │
       │                              └──────┬───────┘
       │                                     │
       │ 5. Webhook Event                   │ 4. Event
       │    (signed, delivered, etc.)       │
       │<────────────────────────────────────┘
       │
       └─> Your webhook handler processes event

Workflow:

Your app dispatches request with ?async=true
Dispatcher returns immediately with dispatchId
Dispatcher processes request with provider
Provider sends event to Dispatcher
Dispatcher forwards event to your webhook URL

Setting Up Webhooks

1. Create Webhook Endpoint

Create an HTTP endpoint that accepts POST requests:

Node.js (Express):

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/docs-dispatcher', (req, res) => {
  const { event, service, provider, data } = req.body;

  console.log(`Received ${service} event: ${event}`);
  console.log('Data:', data);

  // Process the event
  // ...

  // Always respond with 200 OK
  res.status(200).json({ received: true });
});

app.listen(3000);

PHP:

<?php
// webhook.php

$payload = file_get_contents('php://input');
$event = json_decode($payload, true);

error_log("Webhook received: " . $event['event']);

// Process the event
// ...

// Always respond with 200 OK
http_response_code(200);
echo json_encode(['received' => true]);

Java (Spring Boot):

@RestController
@RequestMapping("/webhooks")
public class WebhookController {

    @PostMapping("/docs-dispatcher")
    public ResponseEntity<Map<String, Boolean>> handleWebhook(
        @RequestBody WebhookEvent event
    ) {
        log.info("Received {} event: {}", event.getService(), event.getEvent());

        // Process the event
        // ...

        return ResponseEntity.ok(Map.of("received", true));
    }
}

2. Configure Webhook URL

Provide your webhook URL when dispatching:

curl -X POST https://api.docs-dispatcher.io/api/esign?async=true \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "universign",
    "signers": [...]
  }'

3. Handle Webhook Events

Process events in your webhook handler:

app.post('/webhooks/docs-dispatcher', async (req, res) => {
  // Respond immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  const { event, dispatchId, service, data } = req.body;

  try {
    switch (event) {
      case 'document_signed':
        await handleDocumentSigned(dispatchId, data);
        break;

      case 'document_declined':
        await handleDocumentDeclined(dispatchId, data);
        break;

      case 'letter_delivered':
        await handleLetterDelivered(dispatchId, data);
        break;

      default:
        console.warn(`Unknown event: ${event}`);
    }
  } catch (error) {
    console.error('Error processing webhook:', error);
    // Don't throw - already responded to Dispatcher
  }
});

Webhook Payload Structure

All webhooks include:

{
  "event": "document_signed",
  "timestamp": "2026-02-13T12:30:00Z",
  "dispatchId": "disp_abc123",
  "service": "esign",
  "provider": "universign",
  "data": {
    // Event-specific data
    "documentId": "doc_xyz789",
    "status": "completed",
    "signers": [...]
  }
}

Common Fields:

event - Event type (e.g., "document_signed")
timestamp - ISO 8601 timestamp when event occurred
dispatchId - Original dispatch ID from your request
service - Service name (esign, postal, etc.)
provider - Provider name (universign, signaturit, mysendingbox)
data - Event-specific data

Security

Verify Webhook Signatures

All webhooks include a signature header for verification:

X-Webhook-Signature: sha256=abc123def456...

Verify signature (Node.js):

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  const expected = 'sha256=' + hmac.digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

app.post('/webhooks/docs-dispatcher', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook
  res.status(200).json({ received: true });
});

Get webhook secret: Contact support to obtain your webhook secret, or configure it in Templater UI settings.

HTTPS Only

Webhook URLs must use HTTPS. HTTP endpoints will be rejected.

IP Whitelisting

For additional security, whitelist Dispatcher IPs:

Dispatcher IPs (to whitelist):
  - 52.47.143.xxx (EU region)
  - Contact support for current IP ranges

Best Practices

1. Respond Quickly

Always return 200 OK within 5 seconds:

// ✅ Good - respond immediately
app.post('/webhook', async (req, res) => {
  res.status(200).json({ received: true });
  await processWebhookAsync(req.body); // Process in background
});

// ❌ Bad - slow processing blocks response
app.post('/webhook', async (req, res) => {
  await longRunningProcess(req.body); // 30+ seconds
  res.status(200).json({ received: true });
});

2. Handle Idempotency

Webhooks may be delivered multiple times - use idempotency:

const processedEvents = new Set();

app.post('/webhook', async (req, res) => {
  const eventId = req.body.dispatchId + '_' + req.body.event;

  if (processedEvents.has(eventId)) {
    return res.status(200).json({ received: true, duplicate: true });
  }

  processedEvents.add(eventId);
  res.status(200).json({ received: true });

  await processEvent(req.body);
});

3. Implement Retry Logic

If your webhook fails, Dispatcher retries:

Retry schedule: 1min, 5min, 15min, 1hr, 6hr
Max retries: 5 attempts
Timeout: 10 seconds per attempt

Your endpoint should be idempotent to handle retries gracefully.

4. Log Everything

Log all webhook events for debugging:

app.post('/webhook', (req, res) => {
  const { event, dispatchId, service } = req.body;

  logger.info('Webhook received', {
    event,
    dispatchId,
    service,
    timestamp: new Date().toISOString(),
    payload: req.body
  });

  res.status(200).json({ received: true });
});

5. Monitor Webhook Health

Track webhook delivery success:

Count successful vs failed webhooks
Alert on consecutive failures
Monitor response times
Track event processing delays

Testing Webhooks

Local Testing with ngrok

Test webhooks locally using ngrok:

# Start ngrok
ngrok http 3000

# Use ngrok URL in your dispatch request
curl -X POST https://api.docs-dispatcher.io/api/esign?async=true \
  -d '{
    ...
  }'

Webhook Testing Tools

RequestBin: https://requestbin.com
Webhook.site: https://webhook.site
ngrok: https://ngrok.com

Mock Webhook Events

Test your handler with mock events:

const mockEvent = {
  event: 'document_signed',
  timestamp: new Date().toISOString(),
  dispatchId: 'test_123',
  service: 'esign',
  provider: 'universign',
  data: {
    documentId: 'doc_test',
    status: 'completed'
  }
};

// POST mock event to your handler
await fetch('http://localhost:3000/webhooks/docs-dispatcher', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(mockEvent)
});

Troubleshooting

Webhook Not Received

Check:

✅ Webhook URL is HTTPS
✅ Endpoint returns 200 OK within 5 seconds
✅ No firewall blocking Dispatcher IPs
✅ Using ?async=true query parameter

401/403 Errors

Signature verification failing:

Check webhook secret is correct
Verify signature algorithm matches
Ensure payload hasn't been modified

Timeout Errors

Endpoint too slow:

Respond with 200 OK immediately
Process webhook asynchronously
Optimize slow database queries
Use background job queues

Duplicate Events

Multiple webhooks received:

Implement idempotency using dispatchId + event
Check for duplicate processing in logs
Use database unique constraints

Next Steps

Events Catalog - All available webhook events
eSign Webhooks - Electronic signature events
Postal Webhooks - Mail delivery events
Async Flow Recipe - Complete async workflow example
Troubleshooting - Common webhook issues

PreviousSMS Magic NextEvents Catalog

Last updated 5 days ago

hashtagWhat are Webhooks?

hashtagBenefits

hashtagSupported Services

hashtagHow Webhooks Work

hashtagSetting Up Webhooks

hashtag1. Create Webhook Endpoint

hashtag2. Configure Webhook URL

hashtag3. Handle Webhook Events

hashtagWebhook Payload Structure

hashtagSecurity

hashtagVerify Webhook Signatures

hashtagHTTPS Only

hashtagIP Whitelisting

hashtagBest Practices

hashtag1. Respond Quickly

hashtag2. Handle Idempotency

hashtag3. Implement Retry Logic

hashtag4. Log Everything

hashtag5. Monitor Webhook Health

hashtagTesting Webhooks

hashtagLocal Testing with ngrok

hashtagWebhook Testing Tools

hashtagMock Webhook Events

hashtagTroubleshooting

hashtagWebhook Not Received

hashtag401/403 Errors

hashtagTimeout Errors

hashtagDuplicate Events

hashtagNext Steps

What are Webhooks?

Benefits

Supported Services

How Webhooks Work

Setting Up Webhooks

1. Create Webhook Endpoint

2. Configure Webhook URL

3. Handle Webhook Events

Webhook Payload Structure

Security

Verify Webhook Signatures

HTTPS Only

IP Whitelisting

Best Practices

1. Respond Quickly

2. Handle Idempotency

3. Implement Retry Logic

4. Log Everything

5. Monitor Webhook Health

Testing Webhooks

Local Testing with ngrok

Webhook Testing Tools

Mock Webhook Events

Troubleshooting

Webhook Not Received

401/403 Errors

Timeout Errors

Duplicate Events

Next Steps