Setting up real-time webhooks for letter printing, dispatch, and delivery.

The letter lifecycle state machine: Understanding postal events

The 3-step plan: Implementing real-time postal webhooks

Cryptographic signature verification: Protecting against replay attacks

Technical blueprint: Production Node.js/Express webhook receiver

src/webhooks/letterapi-receiver.ts — typescript
import express, { Request, Response } from 'express';
import crypto from 'crypto';
​
const app = express();
const WEBHOOK_SECRET = process.env.LETTERAPI_WEBHOOK_SECRET || 'whsec_sample_secret_key_84920';
const TOLERANCE_SECONDS = 300; // 5-minute replay tolerance
​
interface LetterEventPayload {
  event: 'letter.created' | 'letter.printed' | 'letter.dispatched' | 'letter.in_transit' | 'letter.delivered' | 'letter.failed';
  letter_id: string;
  timestamp: string;
  data: {
    recipient_name: string;
    postcode: string;
    postage_class: 'first_class' | 'second_class';
    carrier: 'Royal Mail';
    mailmark_barcode?: string;
    delivery_office?: string;
  };
  metadata?: Record<string, any>;
  error?: {
    code: string;
    message: string;
  };
}
​
// Express raw body middleware required for HMAC cryptographic verification
app.post('/api/v1/webhooks/letterapi', express.raw({ type: 'application/json' }), async (req: Request, res: Response) => {
  const sigHeader = req.headers['x-letterapi-signature'] as string;
  const timestampHeader = req.headers['x-letterapi-timestamp'] as string;
​
  if (!sigHeader || !timestampHeader) {
    return res.status(401).json({ error: 'Missing webhook security headers' });
  }
​
  // 1. Enforce Timestamp Tolerance to Prevent Replay Attacks
  const eventTimestamp = parseInt(timestampHeader, 10);
  const currentTimestamp = Math.floor(Date.now() / 1000);
  if (Math.abs(currentTimestamp - eventTimestamp) > TOLERANCE_SECONDS) {
    console.error('[Security Warning] Webhook timestamp outside acceptable tolerance window!');
    return res.status(401).json({ error: 'Webhook timestamp expired' });
  }
​
  // 2. Compute and Verify HMAC SHA-256 Signature
  const rawBody = req.body as Buffer;
  const signedPayload = `${timestampHeader}.${rawBody.toString('utf8')}`;
  const expectedSig = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(signedPayload)
    .digest('hex');
​
  const sigBuffer = Buffer.from(sigHeader, 'hex');
  const expectedBuffer = Buffer.from(expectedSig, 'hex');
​
  if (sigBuffer.length !== expectedBuffer.length || !crypto.timingSafeEqual(sigBuffer, expectedBuffer)) {
    console.error('[Security Alert] Invalid LetterAPI webhook HMAC signature!');
    return res.status(401).json({ error: 'Invalid signature' });
  }
​
  // 3. Deserialize Payload
  const payload: LetterEventPayload = JSON.parse(rawBody.toString('utf8'));
  console.log(`[LetterAPI Webhook] Verified Event: ${payload.event} for Letter: ${payload.letter_id}`);
​
  // 4. Handle Event Asynchronously (e.g. emit to internal event bus or BullMQ queue)
  try {
    switch (payload.event) {
      case 'letter.delivered':
        console.log(`✓ Letter ${payload.letter_id} delivered by Royal Mail to ${payload.data.delivery_office}`);
        // TODO: Update database invoice status to 'NOTICE_SERVED', notify CRM
        break;
      case 'letter.dispatched':
        console.log(`-> Letter ${payload.letter_id} in Royal Mail sorting network`);
        break;
      case 'letter.failed':
        console.error(`✗ Letter ${payload.letter_id} failed: ${payload.error?.message}`);
        break;
    }
​
    // 5. Always return 200 OK promptly to acknowledge receipt
    return res.status(200).json({ received: true });
  } catch (err: any) {
    console.error('[Webhook Processing Error]', err);
    return res.status(500).json({ error: 'Internal processing error' });
  }
});
​
app.listen(4000, () => console.log('LetterAPI webhook listener active on port 4000'));

Building reactive business workflows: Real-world operational automations

Webhook delivery retry policies and high-availability architecture

The failure stakes: What happens when businesses operate with postal blindness

The success transformation: Complete real-time physical visibility

The shared responsibility model for programmatic print and postal infrastructure

Role-Based Access Control (RBAC) and team governance in enterprise accounts

Physical security controls: Clean-room printing, CCTV surveillance, and automated destruction

Penetration testing, vulnerability disclosure, and third-party security audits

The compliance audit checklist: Preparing your hybrid mail stack for regulatory review

Zero-trust architecture in print pipeline: Mutual TLS (mTLS) and token rotation

Data residency guarantees: 100% Sovereign UK data lifecycle and storage limits