⚡Async Flow

Learn how to implement asynchronous dispatch workflows with webhooks for scalable, production-ready integrations.

Overview

Async mode enables:

Immediate response - API returns instantly with dispatch ID
Background processing - Request processed asynchronously
Webhook notification - Results sent to your callback URL
Better scalability - Handle high volumes without blocking
Fault tolerance - Automatic retries and error recovery

This recipe shows complete webhook implementations in 4 languages (Node.js, PHP, Java, and testing with curl).

What You'll Learn

When to use async vs sync mode
How to enable async dispatch
Implementing webhook handlers
Webhook security and verification
Handling retries and idempotency
Complete working examples

Prerequisites

Docs-Dispatcher account with email and password
HTTPS webhook endpoint (required)
Provider configured
Template created
Basic understanding of webhooks

HTTPS Required: Webhook URLs must use HTTPS (not HTTP). HTTP webhooks will be rejected for security reasons.

When to Use Async Mode

Use Async When:

Scenario

Why Async

Long-running operations

Operations taking > 30 seconds

High volume

Processing hundreds/thousands of requests

Background jobs

Batch processing, scheduled tasks

Non-interactive

No user waiting for immediate result

Better UX

Don't block UI while processing

Resilience

Automatic retries on failures

Use Sync When:

Scenario

Why Sync

Quick operations

Expected completion < 10 seconds

Interactive workflows

User waiting for result

Simple error handling

Immediate error feedback needed

Testing/development

Easier debugging

Low volume

Few requests per minute

Async vs Sync Comparison

Aspect

Sync Mode

Async Mode

Response Time

2-30 seconds

< 200ms

Timeout

120 seconds

No timeout

Result

Immediate in response

Via webhook

Scalability

Limited

High

User Experience

Blocks until complete

Instant acknowledgment

Error Handling

Immediate

Via webhook

Use Case

Interactive

Background/Batch

Step 1: Authentication

Dispatcher API uses HTTP Basic Authentication. You'll need your Dispatcher account email and password for all API calls.

Setup Credentials

# Store credentials as environment variables
export EMAIL="[email protected]"
export PASSWORD="your-password"

No token management needed! Unlike JWT-based APIs, Basic Auth doesn't require separate authentication endpoints or token refresh. Your credentials are sent with each request.

Quick links:

Step 2: Enable Async Mode

Add ?async=true query parameter to the endpoint URL:

Sync Mode (Default)

POST /api/invoicing

Async Mode

POST /api/invoicing?async=true

Async Request Example

curl -X POST "https://api.docs-dispatcher.io/api/invoicing?async=true" \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "qonto",
    "documentType": "INVOICE",
    "template": {
      "id": 123,
      "data": {
        "invoiceNumber": "INV-2026-001",
        "date": "2026-02-13",
        "customer": {
          "name": "Acme Corp",
          "email": "[email protected]"
        },
        "items": [...],
        "total": 2400.00
      }
    },
    "metadata": {
      "orderId": "ORD-123",
      "userId": "user_456"
    }
  }'

Immediate Async Response

{
  "success": true,
  "dispatchId": "disp_async_abc123xyz",
  "status": "queued",
  "queuedAt": "2026-02-13T12:30:00Z",
  "estimatedCompletionTime": "2026-02-13T12:32:00Z",
}

Key fields:

dispatchId - Track this ID for status
status - Always "queued" initially
queuedAt - When queued
estimatedCompletionTime - Expected completion (estimate)

Step 3: Implement Webhook Handler

Your webhook endpoint must:

✅ Be accessible via HTTPS
✅ Return 200 OK within 10 seconds
✅ Handle duplicate events (idempotency)
✅ Process async (don't block response)
✅ Verify webhook signatures (recommended)

Webhook Payload Structure

Success Webhook:

{
  "event": "dispatch_completed",
  "dispatchId": "disp_async_abc123xyz",
  "service": "invoicing",
  "documentType": "INVOICE",
  "status": "success",
  "timestamp": "2026-02-13T12:31:45Z",
  "data": {
    "providerResponse": {
      "invoiceId": "qonto_inv_789",
      "invoiceNumber": "INV-2026-001",
      "status": "sent",
      "url": "https://qonto.com/invoices/789",
      "createdAt": "2026-02-13T12:31:45Z"
    },
    "generatedDocument": {
      "url": "https://storage.docs-dispatcher.io/invoices/INV-2026-001.pdf",
      "size": 245678,
      "contentType": "application/pdf"
    }
  },
  "metadata": {
    "orderId": "ORD-123",
    "userId": "user_456"
  },
  "signature": "sha256=abc123def456..."
}

Failure Webhook:

{
  "event": "dispatch_failed",
  "dispatchId": "disp_async_abc123xyz",
  "service": "invoicing",
  "status": "failed",
  "timestamp": "2026-02-13T12:31:45Z",
  "error": {
    "type": "provider_error",
    "message": "Invoice creation failed: Duplicate invoice number",
    "code": "DUPLICATE_INVOICE",
    "details": {
      "invoiceNumber": "INV-2026-001",
      "existingInvoiceId": "qonto_inv_123"
    }
  },
  "metadata": {
    "orderId": "ORD-123",
    "userId": "user_456"
  },
  "signature": "sha256=abc123def456..."
}

Complete Webhook Implementations

Node.js Webhook Handler

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

app.use(express.json());

// Configuration
const CONFIG = {
  webhookSecret: process.env.WEBHOOK_SECRET || 'your-webhook-secret',
  port: process.env.PORT || 3000
};

// Track processed webhooks (use database in production)
const processedWebhooks = new Set();

// Webhook endpoint
app.post('/webhooks/dispatcher', async (req, res) => {
  const webhook = req.body;
  const signature = req.headers['x-dispatcher-signature'];

  console.log('Received webhook:', webhook.event, webhook.dispatchId);

  // Step 1: Verify signature (IMPORTANT for security)
  if (!verifySignature(req.body, signature)) {
    console.error('Invalid webhook signature');
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Step 2: Return 200 OK immediately (don't block)
  res.status(200).json({ received: true });

  // Step 3: Check for duplicates (idempotency)
  if (processedWebhooks.has(webhook.dispatchId)) {
    console.log('Duplicate webhook, skipping:', webhook.dispatchId);
    return;
  }

  // Mark as processed
  processedWebhooks.add(webhook.dispatchId);

  // Step 4: Process webhook asynchronously
  try {
    await processWebhook(webhook);
  } catch (error) {
    console.error('Webhook processing error:', error);
    // Log error but don't fail (already sent 200 OK)
  }
});

// Verify webhook signature
function verifySignature(payload, signature) {
  if (!signature) return false;

  const expectedSignature = crypto
    .createHmac('sha256', CONFIG.webhookSecret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return signature === `sha256=${expectedSignature}`;
}

// Process webhook based on event type
async function processWebhook(webhook) {
  const { event, dispatchId, status } = webhook;

  switch (event) {
    case 'dispatch_completed':
      if (status === 'success') {
        await handleDispatchSuccess(webhook);
      }
      break;

    case 'dispatch_failed':
      await handleDispatchFailure(webhook);
      break;

    default:
      console.warn('Unknown webhook event:', event);
  }
}

// Handle successful dispatch
async function handleDispatchSuccess(webhook) {
  const { dispatchId, service, data, metadata } = webhook;

  console.log('✓ Dispatch completed successfully:', dispatchId);

  // Update database
  await database.updateDispatch(dispatchId, {
    status: 'completed',
    completedAt: new Date(),
    result: data
  });

  // Service-specific handling
  if (service === 'invoicing') {
    await handleInvoiceSuccess(data, metadata);
  } else if (service === 'email') {
    await handleEmailSuccess(data, metadata);
  }
}

// Handle invoice success
async function handleInvoiceSuccess(data, metadata) {
  const { providerResponse, generatedDocument } = data;

  console.log('Invoice created:', providerResponse.invoiceId);
  console.log('Invoice URL:', providerResponse.url);
  console.log('Document URL:', generatedDocument.url);

  // Update order status
  if (metadata.orderId) {
    await database.updateOrder(metadata.orderId, {
      invoiceId: providerResponse.invoiceId,
      invoiceUrl: providerResponse.url,
      status: 'invoiced'
    });
  }

  // Notify customer
  if (metadata.userId) {
    await notificationService.send({
      userId: metadata.userId,
      type: 'invoice_ready',
      data: {
        invoiceUrl: providerResponse.url,
        documentUrl: generatedDocument.url
      }
    });
  }
}

// Handle failed dispatch
async function handleDispatchFailure(webhook) {
  const { dispatchId, error, metadata } = webhook;

  console.error('✗ Dispatch failed:', dispatchId);
  console.error('Error:', error.message);

  // Update database
  await database.updateDispatch(dispatchId, {
    status: 'failed',
    failedAt: new Date(),
    error: error
  });

  // Alert admin
  await alertService.notify({
    level: 'error',
    message: `Dispatch ${dispatchId} failed: ${error.message}`,
    data: {
      dispatchId,
      error,
      metadata
    }
  });

  // Retry logic (optional)
  if (shouldRetry(error)) {
    console.log('Scheduling retry for:', dispatchId);
    await retryQueue.add({
      dispatchId,
      originalRequest: metadata.originalRequest,
      retryCount: (metadata.retryCount || 0) + 1
    });
  }
}

// Determine if error is retryable
function shouldRetry(error) {
  const retryableErrors = [
    'timeout',
    'network_error',
    'provider_unavailable',
    'rate_limit_exceeded'
  ];

  return retryableErrors.includes(error.type);
}

// Start server
app.listen(CONFIG.port, () => {
  console.log(`Webhook server listening on port ${CONFIG.port}`);
});

// Graceful shutdown
process.on('SIGTERM', () => {
  console.log('Shutting down webhook server...');
  server.close(() => {
    console.log('Server closed');
    process.exit(0);
  });
});

PHP Webhook Handler

<?php
// webhook.php

header('Content-Type: application/json');

// Configuration
define('WEBHOOK_SECRET', getenv('WEBHOOK_SECRET') ?: 'your-webhook-secret');
define('LOG_FILE', __DIR__ . '/webhooks.log');

// Step 1: Read webhook payload
$payload = file_get_contents('php://input');
$webhook = json_decode($payload, true);
$signature = $_SERVER['HTTP_X_DISPATCHER_SIGNATURE'] ?? '';

// Logging
logWebhook("Received webhook: {$webhook['event']} - {$webhook['dispatchId']}");

// Step 2: Verify signature
if (!verifySignature($payload, $signature)) {
    logWebhook("Invalid signature for webhook: {$webhook['dispatchId']}");
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// Step 3: Return 200 OK immediately
http_response_code(200);
echo json_encode(['received' => true]);

// Step 4: Process webhook (after response sent)
fastcgi_finish_request(); // Send response and continue processing

try {
    processWebhook($webhook);
} catch (Exception $e) {
    logWebhook("Webhook processing error: " . $e->getMessage());
}

// Verify webhook signature
function verifySignature($payload, $signature) {
    if (empty($signature)) {
        return false;
    }

    $expectedSignature = 'sha256=' . hash_hmac('sha256', $payload, WEBHOOK_SECRET);
    return hash_equals($expectedSignature, $signature);
}

// Process webhook
function processWebhook($webhook) {
    $dispatchId = $webhook['dispatchId'];
    $event = $webhook['event'];

    // Check for duplicates
    if (isProcessed($dispatchId)) {
        logWebhook("Duplicate webhook, skipping: $dispatchId");
        return;
    }

    // Mark as processed
    markProcessed($dispatchId);

    // Handle based on event
    switch ($event) {
        case 'dispatch_completed':
            if ($webhook['status'] === 'success') {
                handleDispatchSuccess($webhook);
            }
            break;

        case 'dispatch_failed':
            handleDispatchFailure($webhook);
            break;

        default:
            logWebhook("Unknown event: $event");
    }
}

// Handle successful dispatch
function handleDispatchSuccess($webhook) {
    $dispatchId = $webhook['dispatchId'];
    $data = $webhook['data'];
    $metadata = $webhook['metadata'];

    logWebhook("✓ Dispatch completed: $dispatchId");

    // Update database
    updateDatabase($dispatchId, [
        'status' => 'completed',
        'completed_at' => date('Y-m-d H:i:s'),
        'result' => json_encode($data)
    ]);

    // Service-specific handling
    if ($webhook['service'] === 'invoicing') {
        handleInvoiceSuccess($data, $metadata);
    }
}

// Handle invoice success
function handleInvoiceSuccess($data, $metadata) {
    $invoiceId = $data['providerResponse']['invoiceId'];
    $invoiceUrl = $data['providerResponse']['url'];

    logWebhook("Invoice created: $invoiceId");

    // Update order
    if (isset($metadata['orderId'])) {
        updateOrder($metadata['orderId'], [
            'invoice_id' => $invoiceId,
            'invoice_url' => $invoiceUrl,
            'status' => 'invoiced'
        ]);
    }

    // Send notification
    if (isset($metadata['userId'])) {
        sendNotification($metadata['userId'], [
            'type' => 'invoice_ready',
            'invoice_url' => $invoiceUrl
        ]);
    }
}

// Handle failed dispatch
function handleDispatchFailure($webhook) {
    $dispatchId = $webhook['dispatchId'];
    $error = $webhook['error'];

    logWebhook("✗ Dispatch failed: $dispatchId - {$error['message']}");

    // Update database
    updateDatabase($dispatchId, [
        'status' => 'failed',
        'failed_at' => date('Y-m-d H:i:s'),
        'error' => json_encode($error)
    ]);

    // Send alert
    sendAlert([
        'level' => 'error',
        'message' => "Dispatch $dispatchId failed: {$error['message']}",
        'data' => $webhook
    ]);
}

// Check if webhook already processed
function isProcessed($dispatchId) {
    // Use Redis or database in production
    $processed = file_get_contents(__DIR__ . '/processed_webhooks.txt');
    return strpos($processed, $dispatchId) !== false;
}

// Mark webhook as processed
function markProcessed($dispatchId) {
    file_put_contents(
        __DIR__ . '/processed_webhooks.txt',
        $dispatchId . "\n",
        FILE_APPEND
    );
}

// Helper functions
function logWebhook($message) {
    $timestamp = date('Y-m-d H:i:s');
    file_put_contents(LOG_FILE, "[$timestamp] $message\n", FILE_APPEND);
}

function updateDatabase($id, $data) {
    // Implement your database update logic
}

function updateOrder($orderId, $data) {
    // Implement order update logic
}

function sendNotification($userId, $data) {
    // Implement notification logic
}

function sendAlert($data) {
    // Implement alerting logic
}

Java Webhook Handler (Spring Boot)

import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;
import org.springframework.http.HttpStatus;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.*;
import java.util.concurrent.*;

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

    private static final String WEBHOOK_SECRET = System.getenv("WEBHOOK_SECRET");
    private final Set<String> processedWebhooks = ConcurrentHashMap.newKeySet();
    private final ExecutorService executor = Executors.newFixedThreadPool(10);

    @PostMapping("/dispatcher")
    public ResponseEntity<Map<String, Boolean>> handleWebhook(
        @RequestBody Map<String, Object> webhook,
        @RequestHeader(value = "X-Dispatcher-Signature", required = false) String signature
    ) {
        String dispatchId = (String) webhook.get("dispatchId");
        String event = (String) webhook.get("event");

        System.out.println("Received webhook: " + event + " - " + dispatchId);

        // Step 1: Verify signature
        if (!verifySignature(webhook, signature)) {
            System.err.println("Invalid signature for webhook: " + dispatchId);
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
                .body(Map.of("error", true));
        }

        // Step 2: Return 200 OK immediately
        ResponseEntity<Map<String, Boolean>> response =
            ResponseEntity.ok(Map.of("received", true));

        // Step 3: Process async (don't block response)
        executor.submit(() -> {
            try {
                processWebhook(webhook);
            } catch (Exception e) {
                System.err.println("Webhook processing error: " + e.getMessage());
            }
        });

        return response;
    }

    private boolean verifySignature(Map<String, Object> webhook, String signature) {
        if (signature == null || signature.isEmpty()) {
            return false;
        }

        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKey = new SecretKeySpec(
                WEBHOOK_SECRET.getBytes(),
                "HmacSHA256"
            );
            mac.init(secretKey);

            String payload = new Gson().toJson(webhook);
            byte[] hash = mac.doFinal(payload.getBytes());
            String expectedSignature = "sha256=" + bytesToHex(hash);

            return expectedSignature.equals(signature);

        } catch (Exception e) {
            System.err.println("Signature verification error: " + e.getMessage());
            return false;
        }
    }

    private void processWebhook(Map<String, Object> webhook) {
        String dispatchId = (String) webhook.get("dispatchId");
        String event = (String) webhook.get("event");

        // Check for duplicates
        if (processedWebhooks.contains(dispatchId)) {
            System.out.println("Duplicate webhook, skipping: " + dispatchId);
            return;
        }

        processedWebhooks.add(dispatchId);

        // Handle based on event
        switch (event) {
            case "dispatch_completed":
                if ("success".equals(webhook.get("status"))) {
                    handleDispatchSuccess(webhook);
                }
                break;

            case "dispatch_failed":
                handleDispatchFailure(webhook);
                break;

            default:
                System.out.println("Unknown event: " + event);
        }
    }

    private void handleDispatchSuccess(Map<String, Object> webhook) {
        String dispatchId = (String) webhook.get("dispatchId");
        Map<String, Object> data = (Map<String, Object>) webhook.get("data");

        System.out.println("✓ Dispatch completed: " + dispatchId);

        // Update database
        // updateDatabase(dispatchId, data);

        // Service-specific handling
        String service = (String) webhook.get("service");
        if ("invoicing".equals(service)) {
            handleInvoiceSuccess(data, webhook.get("metadata"));
        }
    }

    private void handleInvoiceSuccess(Map<String, Object> data, Object metadata) {
        Map<String, Object> providerResponse =
            (Map<String, Object>) data.get("providerResponse");

        String invoiceId = (String) providerResponse.get("invoiceId");
        String invoiceUrl = (String) providerResponse.get("url");

        System.out.println("Invoice created: " + invoiceId);
        System.out.println("Invoice URL: " + invoiceUrl);

        // Update order, send notifications, etc.
    }

    private void handleDispatchFailure(Map<String, Object> webhook) {
        String dispatchId = (String) webhook.get("dispatchId");
        Map<String, Object> error = (Map<String, Object>) webhook.get("error");

        System.err.println("✗ Dispatch failed: " + dispatchId);
        System.err.println("Error: " + error.get("message"));

        // Send alert, log error, etc.
    }

    private static String bytesToHex(byte[] bytes) {
        StringBuilder result = new StringBuilder();
        for (byte b : bytes) {
            result.append(String.format("%02x", b));
        }
        return result.toString();
    }
}

Webhook Security

1. Verify Signatures

Always verify webhook signatures to prevent spoofed requests:

function verifySignature(payload, signature) {
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');

  return signature === `sha256=${expectedSignature}`;
}

2. Use HTTPS Only

if (req.protocol !== 'https') {
  return res.status(403).json({ error: 'HTTPS required' });
}

3. Implement Rate Limiting

const rateLimit = require('express-rate-limit');

const webhookLimiter = rateLimit({
  windowMs: 1 * 60 * 1000, // 1 minute
  max: 100 // Max 100 requests per minute
});

app.post('/webhooks/dispatcher', webhookLimiter, handleWebhook);

Idempotency

Handle duplicate webhooks gracefully:

// Using database
async function isProcessed(dispatchId) {
  const record = await db.query(
    'SELECT 1 FROM processed_webhooks WHERE dispatch_id = ?',
    [dispatchId]
  );
  return record.length > 0;
}

async function markProcessed(dispatchId) {
  await db.query(
    'INSERT INTO processed_webhooks (dispatch_id, processed_at) VALUES (?, NOW())',
    [dispatchId]
  );
}

// Using Redis
async function isProcessedRedis(dispatchId) {
  return await redis.exists(`webhook:${dispatchId}`);
}

async function markProcessedRedis(dispatchId) {
  await redis.setex(`webhook:${dispatchId}`, 86400, '1'); // 24h TTL
}

Testing Webhooks

Test with ngrok

# Install ngrok
npm install -g ngrok

# Start your webhook server
node webhook-server.js

# Expose to internet
ngrok http 3000

https://abc123.ngrok.io/webhooks/dispatcher

Manual Webhook Testing

# Simulate webhook
curl -X POST https://your-app.com/webhooks/dispatcher \
  -H "Content-Type: application/json" \
  -H "X-Dispatcher-Signature: sha256=test" \
  -d '{
    "event": "dispatch_completed",
    "dispatchId": "test_123",
    "status": "success",
    "data": {...}
  }'

Retry Logic

Implement exponential backoff for failed webhooks:

async function retryWithBackoff(fn, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
      console.log(`Retry attempt ${attempt + 1} after ${delay}ms`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Next Steps

Invoice - Invoice with async mode
Validate then Send - Validation patterns
Troubleshooting - Debug webhook issues

Core Concepts

Summary

You've learned:

✅ When to use async vs sync mode
✅ How to enable async dispatch
✅ Implementing secure webhook handlers
✅ Handling idempotency and retries
✅ Complete implementations in Node.js, PHP, Java
✅ Testing and debugging webhooks

Async mode with webhooks is essential for production scalability!

PreviousValidate then Send NextEmail Dispatch

Last updated 5 days ago

hashtagOverview

hashtagWhat You'll Learn

hashtagPrerequisites

hashtagWhen to Use Async Mode

hashtagUse Async When:

hashtagUse Sync When:

hashtagAsync vs Sync Comparison

hashtagStep 1: Authentication

hashtagSetup Credentials

hashtagStep 2: Enable Async Mode

hashtagSync Mode (Default)

hashtagAsync Mode

hashtagAsync Request Example

hashtagImmediate Async Response

hashtagStep 3: Implement Webhook Handler

hashtagWebhook Payload Structure

hashtagComplete Webhook Implementations

hashtagNode.js Webhook Handler

hashtagPHP Webhook Handler

hashtagJava Webhook Handler (Spring Boot)

hashtagWebhook Security

hashtag1. Verify Signatures

hashtag2. Use HTTPS Only

hashtag3. Implement Rate Limiting

hashtagIdempotency

hashtagTesting Webhooks

hashtagTest with ngrok

hashtagManual Webhook Testing

hashtagRetry Logic

hashtagNext Steps

hashtagRelated Recipes

hashtagCore Concepts

hashtagSummary

Overview

What You'll Learn

Prerequisites

When to Use Async Mode

Use Async When:

Use Sync When:

Async vs Sync Comparison

Step 1: Authentication

Setup Credentials

Step 2: Enable Async Mode

Sync Mode (Default)

Async Mode

Async Request Example

Immediate Async Response

Step 3: Implement Webhook Handler

Webhook Payload Structure

Complete Webhook Implementations

Node.js Webhook Handler

PHP Webhook Handler

Java Webhook Handler (Spring Boot)

Webhook Security

1. Verify Signatures

2. Use HTTPS Only

3. Implement Rate Limiting

Idempotency

Testing Webhooks

Test with ngrok

Manual Webhook Testing

Retry Logic

Next Steps

Related Recipes

Core Concepts

Summary