API Reference

Webhooks

Receive real-time events as letters are processed. Configure up to 10 webhook endpoints per organisation, each subscribing to specific event types.

Real-time

Events fire within seconds of the action occurring.

Signed

Every delivery includes an HMAC-SHA256 signature for verification.

Reliable

Failed deliveries retry with exponential backoff. History viewable in dashboard.

Signature verification

Every webhook delivery includes an X-ComplyPost-Signature header containing an HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret.

Header	Description
X-ComplyPost-Signature	HMAC-SHA256 hex digest
X-ComplyPost-Event	Event type (e.g. `letter.classified`)
X-ComplyPost-Delivery	Unique delivery ID for idempotency

Node.js

javascript

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

const rawBody = req.body; // raw string, not parsed JSON
const sig = req.headers['x-complypost-signature'];

if (!verifyWebhook(rawBody, sig, process.env.WEBHOOK_SECRET)) {
  return res.status(401).json({ error: 'Invalid signature' });
}

const event = JSON.parse(rawBody);
console.log('Verified event:', event.event);

Python

python

import hmac, hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

raw_body = request.get_data()
sig = request.headers.get('X-ComplyPost-Signature', '')

if not verify_webhook(raw_body, sig, WEBHOOK_SECRET):
    abort(401)

Webhook events

letter.received

Triggered when a new letter is scanned and enters the processing pipeline.

Example payload

{
  "event": "letter.received",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "letterId": "let_abc123",
    "orgId": "org_def456",
    "batchId": "bat_xyz789",
    "pages": 2,
    "format": "pdf"
  }
}

letter.classified

Triggered after AI classification is complete — includes sender, category, priority, summary, and extracted deadlines.

Example payload

{
  "event": "letter.classified",
  "timestamp": "2025-01-15T10:30:05Z",
  "data": {
    "letterId": "let_abc123",
    "orgId": "org_def456",
    "sender": "HMRC",
    "recipientCompany": "Acme Ltd",
    "companyNumber": "12345678",
    "priority": "high",
    "category": "tax",
    "subject": "Self Assessment Tax Return Notice",
    "summary": "HMRC notice regarding the 2024/25 Self Assessment filing deadline.",
    "deadlines": ["2025-01-31"]
  }
}

letter.urgent

Triggered when a letter is classified as critical or high priority — ideal for instant alerts.

Example payload

{
  "event": "letter.urgent",
  "timestamp": "2025-01-15T10:30:05Z",
  "data": {
    "letterId": "let_abc123",
    "orgId": "org_def456",
    "priority": "critical",
    "sender": "Companies House",
    "recipientCompany": "Acme Ltd",
    "subject": "Compulsory Strike-Off Notice",
    "deadlines": ["2025-02-15"]
  }
}

letter.delivered

Triggered when a classified letter is successfully emailed to the client.

Example payload

{
  "event": "letter.delivered",
  "timestamp": "2025-01-15T11:00:00Z",
  "data": {
    "letterId": "let_abc123",
    "orgId": "org_def456",
    "deliveryId": "del_ghi012",
    "recipientEmail": "[email protected]",
    "recipientCompany": "Acme Ltd",
    "status": "delivered"
  }
}

batch.completed

Triggered when all letters in a batch have been processed.

Example payload

{
  "event": "batch.completed",
  "timestamp": "2025-01-15T10:45:00Z",
  "data": {
    "batchId": "bat_xyz789",
    "orgId": "org_def456",
    "totalLetters": 47,
    "classified": 45,
    "urgent": 3,
    "deadlinesDetected": 8,
    "processingTimeSeconds": 312
  }
}

Management endpoints

Method	Endpoint	Description	Auth
GET	/webhooks	List all webhooks for your organisation.	Bearer token
POST	/webhooks	Create a new webhook endpoint. Returns the signing secret (shown once).	Bearer token (Owner/Admin)
PATCH	/webhooks/:id	Update webhook URL, events, description, or active status.	Bearer token (Owner/Admin)
DELETE	/webhooks/:id	Delete a webhook endpoint.	Bearer token (Owner/Admin)
POST	/webhooks/:id/test	Send a test delivery to verify your endpoint.	Bearer token (Owner/Admin)
GET	/webhooks/:id/deliveries	List delivery history with filtering.	Bearer token
POST	/webhooks/:id/rotate-secret	Rotate the HMAC signing secret.	Bearer token (Owner/Admin)