Webhooks

Settler can send webhooks to notify your application of important events, such as when a reconciliation job completes or fails.

Setting Up Webhooks

Configure webhooks in the Console:

Go to Console → Webhooks
Click "Add Webhook"
Enter your endpoint URL
Select events to subscribe to
Save and verify

Webhook Events

reconciliation.completed - Job completed successfully
reconciliation.failed - Job failed
receipt.parsed - Receipt parsing completed

Webhook Payload

{
  "event": "reconciliation.completed",
  "data": {
    "jobId": "job_123",
    "workspaceId": "ws_456",
    "status": "completed",
    "summary": {
      "total": 150,
      "matched": 145,
      "unmatched": 3,
      "conflicts": 2
    }
  },
  "timestamp": "2025-12-18T12:00:00Z"
}

Verifying Webhooks

Webhooks include a signature header that you can verify to ensure the request came from Settler.

import crypto from 'crypto';

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