⏱️Sync vs Async

Docs-Dispatcher supports both synchronous and asynchronous execution modes. This guide explains the differences, when to use each mode, and best practices for handling responses.

Quick Comparison

Feature

Sync (?async=false)

Async (?async=true)

Response time

Waits for completion (seconds to minutes)

Immediate (< 5 seconds)

Returns

Full provider response

Dispatch ID only

Best for

Quick operations (< 2 min)

Long operations, batch jobs

Timeout

120 seconds

No timeout (queued)

Notifications

Response only

Webhook callback

Error handling

Immediate in response

Via webhook

Resource usage

Blocks connection

Non-blocking

Synchronous Mode (Default)

In synchronous mode, the API waits for the entire operation to complete before returning a response.

How It Works

Client Request → Dispatcher → Provider API → Response → Client
                  ↓
              Wait for completion
              (blocks connection)

Request:

POST /api/invoicing?async=false
# or simply
POST /api/invoicing

Execution flow:

Client sends request
Dispatcher validates request
Dispatcher calls provider API
Dispatcher waits for provider response
Dispatcher returns full response to client

Example Request

curl -X POST https://api.docs-dispatcher.io/api/invoicing?async=false \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "qonto",
    "documentType": "INVOICE",
    "template": {
      "id": 123,
      "data": {...}
    }
  }'

Example Response (Immediate)

{
  "success": true,
  "dispatchId": "disp_sync_abc123",
  "providerResponse": {
    "invoiceId": "qonto_inv_789",
    "status": "sent",
    "url": "https://qonto.com/invoices/789",
    "createdAt": "2026-02-13T12:30:00Z"
  },
  "generatedDocument": {
    "url": "https://storage.docs-dispatcher.io/invoices/INV-2026-001.pdf",
    "size": 245678,
    "contentType": "application/pdf"
  },
  "executionTime": 2.3
}

When to Use Sync Mode

Use synchronous mode when:

User is waiting for result - User interface needs immediate feedback
Quick operations - Expected completion time < 30 seconds
Simple workflows - Single service dispatch without chaining
Interactive testing - Development and debugging
Simple error handling - Handle errors in same request/response

Sync Mode Advantages

Immediate results - Get response right away
Simpler code - No webhook handling needed
Easier debugging - Errors returned directly
No infrastructure - No webhook endpoint required

Sync Mode Disadvantages

Connection blocking - Client waits for completion
Timeout risk - 120-second limit may not be enough
Resource usage - Holds server resources during wait
No progress updates - All or nothing response

Asynchronous Mode

In asynchronous mode, the request is queued immediately and processed in the background.

How It Works

Client Request → Dispatcher → Queue → Client (dispatchId)
                               ↓
                         Background worker
                               ↓
                         Provider API
                               ↓
                         Webhook callback

Request:

POST /api/invoicing?async=true

Execution flow:

Client sends request
Dispatcher validates request
Dispatcher queues job
Dispatcher returns dispatch ID immediately
Background worker processes job
Worker calls provider API

Example Request

curl -X POST https://api.docs-dispatcher.io/api/invoicing?async=true \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "qonto",
    "documentType": "INVOICE",
    "template": {
      "id": 123,
      "data": {...}
    },
  }'

Example Response (Immediate)

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

Example Webhook Payload (Later)

When processing completes, your webhook receives:

POST https://your-app.com/webhooks/dispatcher

{
  "event": "dispatch_completed",
  "dispatchId": "disp_async_def456",
  "service": "invoicing",
  "status": "success",
  "timestamp": "2026-02-13T12:31:45Z",
  "data": {
    "providerResponse": {
      "invoiceId": "qonto_inv_789",
      "status": "sent",
      "url": "https://qonto.com/invoices/789"
    },
    "generatedDocument": {
      "url": "https://storage.docs-dispatcher.io/invoices/INV-2026-001.pdf",
      "size": 245678
    }
  },
  "metadata": {
    "orderId": "ORD-2026-12345"
  }
}

When to Use Async Mode

Use asynchronous mode when:

Long operations - Expected completion > 30 seconds
Batch processing - Processing many dispatches
Non-critical timing - User doesn't need immediate result
High volume - Many concurrent requests
Background jobs - Cron jobs, scheduled tasks
Complex workflows - Multi-service composition

Async Mode Advantages

No timeouts - No 120-second limit
Better resource usage - Non-blocking connections
Scalability - Handle high volumes
Progress tracking - Webhook events provide updates
Resilience - Automatic retries on failure

Async Mode Disadvantages

Complexity - Requires webhook endpoint
Infrastructure - Need to handle webhooks
Delayed results - Not suitable for interactive use
Debugging - Harder to trace execution

Webhook Implementation

For async mode, you must implement a webhook endpoint to receive completion notifications.

Webhook Endpoint Requirements

HTTPS required - HTTP not supported for security
Return 200 OK - Within 10 seconds
Idempotency - Handle duplicate events gracefully
Authentication - Verify webhook signature (optional but recommended)

Webhook Handler Example (Node.js)

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

app.use(express.json());

app.post('/webhooks/dispatcher', async (req, res) => {
  const webhook = req.body;

  console.log('Webhook received:', webhook.event);

  try {
    // Verify webhook signature (optional but recommended)
    // verifyWebhookSignature(req.headers['x-dispatcher-signature'], req.body);

    // Handle webhook based on event type
    switch (webhook.event) {
      case 'dispatch_completed':
        await handleDispatchCompleted(webhook);
        break;
      case 'dispatch_failed':
        await handleDispatchFailed(webhook);
        break;
      case 'signature_completed':
        await handleSignatureCompleted(webhook);
        break;
      default:
        console.warn('Unknown webhook event:', webhook.event);
    }

    // MUST return 200 OK quickly
    res.status(200).json({ received: true });

  } catch (error) {
    console.error('Webhook processing error:', error);
    // Still return 200 to prevent retries
    res.status(200).json({ received: true, error: error.message });
  }
});

async function handleDispatchCompleted(webhook) {
  const { dispatchId, service, data } = webhook;

  // Update your database
  await database.updateDispatch(dispatchId, {
    status: 'completed',
    providerResponse: data.providerResponse,
    completedAt: webhook.timestamp
  });

  // Notify user
  await notifyUser(dispatchId, 'Your invoice has been sent!');
}

async function handleDispatchFailed(webhook) {
  const { dispatchId, error } = webhook;

  // Log error
  await database.updateDispatch(dispatchId, {
    status: 'failed',
    error: error,
    failedAt: webhook.timestamp
  });

  // Alert admin
  await alertAdmin(`Dispatch ${dispatchId} failed: ${error.message}`);
}

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Webhook Handler Example (PHP)

<?php
// webhook.php

$webhookPayload = file_get_contents('php://input');
$webhook = json_decode($webhookPayload, true);

// Verify webhook signature (optional but recommended)
// verifyWebhookSignature($_SERVER['HTTP_X_DISPATCHER_SIGNATURE'], $webhookPayload);

// Handle webhook
try {
    switch ($webhook['event']) {
        case 'dispatch_completed':
            handleDispatchCompleted($webhook);
            break;
        case 'dispatch_failed':
            handleDispatchFailed($webhook);
            break;
        case 'signature_completed':
            handleSignatureCompleted($webhook);
            break;
        default:
            error_log('Unknown webhook event: ' . $webhook['event']);
    }

    // MUST return 200 OK
    http_response_code(200);
    echo json_encode(['received' => true]);

} catch (Exception $e) {
    error_log('Webhook error: ' . $e->getMessage());
    // Still return 200 to prevent retries
    http_response_code(200);
    echo json_encode(['received' => true, 'error' => $e->getMessage()]);
}

function handleDispatchCompleted($webhook) {
    $db = getDatabase();
    $db->updateDispatch($webhook['dispatchId'], [
        'status' => 'completed',
        'provider_response' => json_encode($webhook['data']['providerResponse']),
        'completed_at' => $webhook['timestamp']
    ]);

    // Notify user
    notifyUser($webhook['dispatchId'], 'Your invoice has been sent!');
}

function handleDispatchFailed($webhook) {
    $db = getDatabase();
    $db->updateDispatch($webhook['dispatchId'], [
        'status' => 'failed',
        'error' => json_encode($webhook['error']),
        'failed_at' => $webhook['timestamp']
    ]);

    // Alert admin
    alertAdmin("Dispatch {$webhook['dispatchId']} failed: {$webhook['error']['message']}");
}

Webhook Handler Example (Java)

import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;

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

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

        try {
            // Verify webhook signature (optional but recommended)
            // verifyWebhookSignature(signature, webhook);

            // Handle webhook based on event type
            switch (event) {
                case "dispatch_completed":
                    handleDispatchCompleted(webhook);
                    break;
                case "dispatch_failed":
                    handleDispatchFailed(webhook);
                    break;
                case "signature_completed":
                    handleSignatureCompleted(webhook);
                    break;
                default:
                    logger.warn("Unknown webhook event: {}", event);
            }

            // MUST return 200 OK quickly
            return ResponseEntity.ok(Map.of("received", true));

        } catch (Exception e) {
            logger.error("Webhook processing error", e);
            // Still return 200 to prevent retries
            return ResponseEntity.ok(Map.of(
                "received", true,
                "error", e.getMessage()
            ));
        }
    }

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

        // Update database
        dispatchRepository.updateStatus(dispatchId, "completed", data);

        // Notify user
        notificationService.notifyUser(dispatchId, "Your invoice has been sent!");
    }

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

        // Update database
        dispatchRepository.updateStatus(dispatchId, "failed", error);

        // Alert admin
        alertService.alertAdmin("Dispatch " + dispatchId + " failed: " + error.get("message"));
    }
}

Polling vs Webhooks

For async operations, you can either use webhooks or poll for status.

Webhooks (Recommended)

Pros:

Real-time notifications
No polling overhead
Lower latency
More efficient

Cons:

Requires public endpoint
More complex setup
Need to handle retries

Polling (Alternative)

# Get dispatch status
GET /api/dispatches/{dispatchId}

Response:

{
  "dispatchId": "disp_async_def456",
  "status": "completed",
  "service": "invoicing",
  "createdAt": "2026-02-13T12:30:00Z",
  "completedAt": "2026-02-13T12:31:45Z",
  "result": {
    "providerResponse": {...},
    "generatedDocument": {...}
  }
}

Polling example:

async function pollDispatchStatus(dispatchId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.docs-dispatcher.io/api/dispatches/${dispatchId}`,
      {
        headers: { 'Authorization': `Bearer ${jwtToken}` }
      }
    );

    const status = await response.json();

    if (status.status === 'completed') {
      return status.result;
    }

    if (status.status === 'failed') {
      throw new Error(status.error.message);
    }

    // Wait 5 seconds before next poll
    await new Promise(resolve => setTimeout(resolve, 5000));
  }

  throw new Error('Dispatch timeout after 5 minutes');
}

// Usage
const dispatchId = 'disp_async_def456';
const result = await pollDispatchStatus(dispatchId);
console.log('Dispatch completed:', result);

Pros:

No webhook endpoint needed
Simpler setup
Works behind firewalls

Cons:

Higher latency
More API calls
Less efficient
Can miss events

Timeout Considerations

Sync Mode Timeouts

Synchronous requests have a 120-second timeout:

Request sent → 120 seconds max → Response or timeout

What happens on timeout:

{
  "error": "timeout",
  "message": "Request timed out after 120 seconds. Operation may still complete in background.",
  "dispatchId": "disp_sync_timeout_abc",
  "suggestion": "Use async mode for long-running operations"
}

Operations likely to timeout (use async instead):

Large document generation (> 50 pages)
Multi-signer eSign workflows
International postal dispatch
Batch operations

Async Mode (No Timeout)

Asynchronous requests never timeout:

Queue immediately (< 5 seconds)
Process in background (unlimited time)
Webhook notification on completion

Best Practices

1. Choose Mode Based on Duration

function chooseExecutionMode(estimatedDuration) {
  if (estimatedDuration < 30) {
    return 'sync';  // Quick operations
  } else {
    return 'async'; // Long operations
  }
}

2. Use Async for Batch Operations

// ❌ Bad - sync for batch
for (const invoice of invoices) {
  await dispatchInvoice(invoice, { async: false }); // Blocks each time
}

// ✅ Good - async for batch
const dispatchIds = [];
for (const invoice of invoices) {
  const result = await dispatchInvoice(invoice, { async: true });
  dispatchIds.push(result.dispatchId);
}
// Process completions via webhooks

3. Implement Webhook Retries

Dispatcher retries failed webhooks up to 3 times:

Attempt 1: Immediate
Attempt 2: After 1 minute
Attempt 3: After 5 minutes
Attempt 4: After 15 minutes (final)

Handle retries idempotently:

const processedWebhooks = new Set();

app.post('/webhooks/dispatcher', (req, res) => {
  const dispatchId = req.body.dispatchId;

  // Check if already processed
  if (processedWebhooks.has(dispatchId)) {
    console.log('Duplicate webhook, skipping:', dispatchId);
    return res.status(200).json({ received: true, duplicate: true });
  }

  // Process webhook
  processWebhook(req.body);

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

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

4. Monitor Async Queue

Track async dispatch status:

async function trackAsyncDispatch(dispatchId) {
  const status = await fetch(
    `https://api.docs-dispatcher.io/api/dispatches/${dispatchId}`,
    {
      headers: { 'Authorization': `Bearer ${jwtToken}` }
    }
  );

  const data = await status.json();

  return {
    dispatchId: data.dispatchId,
    status: data.status,
    queuedAt: data.createdAt,
    estimatedCompletion: data.estimatedCompletionTime
  };
}

5. Fallback Strategy

Combine sync with async fallback:

async function dispatchWithFallback(request) {
  try {
    // Try sync first (faster for user)
    const response = await fetch(
      'https://api.docs-dispatcher.io/api/invoicing?async=false',
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${jwtToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(request),
        timeout: 30000 // 30 second timeout
      }
    );

    return await response.json();

  } catch (error) {
    if (error.name === 'TimeoutError') {
      // Fallback to async
      console.log('Sync timeout, switching to async');

      const response = await fetch(
        'https://api.docs-dispatcher.io/api/invoicing?async=true',
        {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${jwtToken}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            ...request,
          })
        }
      );

      return await response.json();
    }

    throw error;
  }
}

Error Handling

Sync Mode Errors

Errors returned immediately in response:

{
  "success": false,
  "error": "provider_error",
  "message": "Invoice creation failed: Duplicate invoice number",
  "providerError": {
    "code": "DUPLICATE_INVOICE",
    "details": "Invoice INV-2026-001 already exists"
  }
}

Async Mode Errors

Errors sent via webhook:

{
  "event": "dispatch_failed",
  "dispatchId": "disp_async_def456",
  "service": "invoicing",
  "status": "failed",
  "timestamp": "2026-02-13T12:31:45Z",
  "error": {
    "type": "provider_error",
    "message": "Invoice creation failed: Duplicate invoice number",
    "providerError": {
      "code": "DUPLICATE_INVOICE",
      "details": "Invoice INV-2026-001 already exists"
    }
  }
}

Provider Configurations - Configure providers
Request Model - Understand request structure
Validation - Test before dispatch
Webhooks - Webhook event catalog

Summary

Choose Sync when:

User is waiting for result
Operation completes quickly (< 30s)
Simple error handling
Testing/debugging

Choose Async when:

Long-running operations (> 30s)
Batch processing
Background jobs
High volume/scalability

Key differences:

Sync: Immediate response, 120s timeout, blocks connection
Async: Queue immediately, no timeout, webhook notification

Understanding execution modes helps you build robust, scalable integrations with Docs-Dispatcher.

PreviousProviders & Configurations NextValidation

Last updated 5 days ago

hashtagQuick Comparison

hashtagSynchronous Mode (Default)

hashtagHow It Works

hashtagExample Request

hashtagExample Response (Immediate)

hashtagWhen to Use Sync Mode

hashtagSync Mode Advantages

hashtagSync Mode Disadvantages

hashtagAsynchronous Mode

hashtagHow It Works

hashtagExample Request

hashtagExample Response (Immediate)

hashtagExample Webhook Payload (Later)

hashtagWhen to Use Async Mode

hashtagAsync Mode Advantages

hashtagAsync Mode Disadvantages

hashtagWebhook Implementation

hashtagWebhook Endpoint Requirements

hashtagWebhook Handler Example (Node.js)

hashtagWebhook Handler Example (PHP)

hashtagWebhook Handler Example (Java)

hashtagPolling vs Webhooks

hashtagWebhooks (Recommended)

hashtagPolling (Alternative)

hashtagTimeout Considerations

hashtagSync Mode Timeouts

hashtagAsync Mode (No Timeout)

hashtagBest Practices

hashtag1. Choose Mode Based on Duration

hashtag2. Use Async for Batch Operations

hashtag3. Implement Webhook Retries

hashtag4. Monitor Async Queue

hashtag5. Fallback Strategy

hashtagError Handling

hashtagSync Mode Errors

hashtagAsync Mode Errors

hashtagRelated Documentation

hashtagSummary

Quick Comparison

Synchronous Mode (Default)

How It Works

Example Request

Example Response (Immediate)

When to Use Sync Mode

Sync Mode Advantages

Sync Mode Disadvantages

Asynchronous Mode

How It Works

Example Request

Example Response (Immediate)

Example Webhook Payload (Later)

When to Use Async Mode

Async Mode Advantages

Async Mode Disadvantages

Webhook Implementation

Webhook Endpoint Requirements

Webhook Handler Example (Node.js)

Webhook Handler Example (PHP)

Webhook Handler Example (Java)

Polling vs Webhooks

Webhooks (Recommended)

Polling (Alternative)

Timeout Considerations

Sync Mode Timeouts

Async Mode (No Timeout)

Best Practices

1. Choose Mode Based on Duration

2. Use Async for Batch Operations

3. Implement Webhook Retries

4. Monitor Async Queue

5. Fallback Strategy

Error Handling

Sync Mode Errors

Async Mode Errors

Related Documentation

Summary