📮Postal Events

Webhook events for Postal service providers.

Overview

The following Postal providers support webhook notifications:

• Mysendingbox

Mysendingbox Events

Events

letter_created

Letter was created and queued

Payload Example:

{
  "event": "letter_created",
  "timestamp": "2026-02-13T12:30:00Z",
  "dispatchId": "disp_abc123",
  "provider": "mysendingbox",
  "service": "postal",
  "data": {
    "letterId": "letter_abc123",
    "status": "delivered",
    "trackingNumber": "TRACK123456",
    "deliveredAt": "2026-02-15T10:00:00Z"
  }
}

letter_in_transit

Letter is in transit to recipient

Payload Example:

{
  "event": "letter_in_transit",
  "timestamp": "2026-02-13T12:30:00Z",
  "dispatchId": "disp_abc123",
  "provider": "mysendingbox",
  "service": "postal",
  "data": {
    "letterId": "letter_abc123",
    "status": "delivered",
    "trackingNumber": "TRACK123456",
    "deliveredAt": "2026-02-15T10:00:00Z"
  }
}

letter_delivered

Letter was delivered

Payload Example:

{
  "event": "letter_delivered",
  "timestamp": "2026-02-13T12:30:00Z",
  "dispatchId": "disp_abc123",
  "provider": "mysendingbox",
  "service": "postal",
  "data": {
    "letterId": "letter_abc123",
    "status": "delivered",
    "trackingNumber": "TRACK123456",
    "deliveredAt": "2026-02-15T10:00:00Z"
  }
}

letter_failed

Letter delivery failed

Payload Example:

{
  "event": "letter_failed",
  "timestamp": "2026-02-13T12:30:00Z",
  "dispatchId": "disp_abc123",
  "provider": "mysendingbox",
  "service": "postal",
  "data": {
    "letterId": "letter_abc123",
    "status": "delivered",
    "trackingNumber": "TRACK123456",
    "deliveredAt": "2026-02-15T10:00:00Z"
  }
}

letter_returned

Letter was returned to sender

Payload Example:

{
  "event": "letter_returned",
  "timestamp": "2026-02-13T12:30:00Z",
  "dispatchId": "disp_abc123",
  "provider": "mysendingbox",
  "service": "postal",
  "data": {
    "letterId": "letter_abc123",
    "status": "delivered",
    "trackingNumber": "TRACK123456",
    "deliveredAt": "2026-02-15T10:00:00Z"
  }
}

Webhook URL

Configure this URL in Mysendingbox dashboard:

POST https://api.docs-dispatcher.io/api/webhooks/postal/providers/mysendingbox/endpoint.json

Handler Example (Node.js)

app.post('/webhooks/postal/mysendingbox', async (req, res) => {
  const { event, data, dispatchId } = req.body;

  console.log(`Received mysendingbox event: ${event}`);

  switch (event) {
    case 'letter_created':
      // Handle letter was created and queued
      await handleLettercreated(data);
      break;

    case 'letter_in_transit':
      // Handle letter is in transit to recipient
      await handleLetterintransit(data);
      break;

    case 'letter_delivered':
      // Handle letter was delivered
      await handleLetterdelivered(data);
      break;

    case 'letter_failed':
      // Handle letter delivery failed
      await handleLetterfailed(data);
      break;

    case 'letter_returned':
      // Handle letter was returned to sender
      await handleLetterreturned(data);
      break;

    default:
      console.warn(`Unknown event type: ${event}`);
  }

  // Always return 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

Best Practices

1. Respond Quickly

Always return 200 OK within 5 seconds:

// ✅ Good - acknowledge immediately, process async
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); // Takes 30+ seconds
  res.status(200).json({ received: true });
});

2. Verify Signatures

Always verify webhook signatures to prevent spoofing:

const signature = req.headers['x-webhook-signature'];
if (!verifySignature(req.body, signature, secret)) {
  return res.status(401).json({ error: 'Invalid signature' });
}

3. Handle Idempotency

Webhooks may be delivered multiple times - use idempotency:

const eventId = req.body.dispatchId + '_' + req.body.event;
if (await isProcessed(eventId)) {
  return res.status(200).json({ received: true, duplicate: true });
}
await markProcessed(eventId);

Next Steps

• Webhook Fundamentals

• Events Catalog

• Async Dispatch Recipe

• Mysendingbox Provider