Webhooks

Overview

Webhooks allow BillerAPI to push event notifications to your server in real time. Instead of polling for changes, register a webhook URL and we'll send HTTP POST requests when events occur.

Registering a Webhook

curl -X POST https://sandbox.api.billerapi.com/iam/clients/{clientId}/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "environment": "sandbox",
    "url": "https://your-server.com/webhooks/billerapi",
    "events": ["bill.created", "bill.updated", "account-link.created"],
    "secret": "whsec_your_signing_secret"
  }'

Payload Format

Every webhook delivery sends a JSON payload with a consistent envelope structure. The data field contains minimal resource IDs — fetch full details from the API.

{
  "event_type": "bill.created",
  "event_id": "evt_abc123",
  "timestamp": "2026-03-27T10:00:00Z",
  "client_id": "client_xyz",
  "data": {
    "bill_id": "bill_456",
    "account_link_id": "link_789",
    "client_user_id": "user_123"
  }
}

HTTP Headers

Event Reference

Click an event to see its full payload example and recommended handling.

Event Details

Webhook Security

If you provide a secret when registering your webhook, every delivery includes an HMAC-SHA256 signature in theX-Webhook-Signature header. Always verify this signature before processing events.

import crypto from 'crypto';

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('base64');

  const received = signature.replace('sha256=', '');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(received),
  );
}

// In your webhook handler:
app.post('/webhooks/billerapi', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET,
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the event...
  res.status(200).json({ received: true });
});

Retry Policy

If your endpoint returns a non-2xx status code or doesn't respond within 10 seconds, we retry with exponential backoff.

• Your endpoint must respond within 10 seconds
• Return any 2xx status to acknowledge receipt
• Failed deliveries are retried with exponential backoff
• Use the X-Webhook-Id header for deduplication

Testing with Sandbox

Use the sandbox trigger endpoint to simulate webhook events and test your handler.

curl -X POST https://sandbox.api.billerapi.com/sandbox/trigger-event \
  -H "Content-Type: application/json" \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret" \
  -d '{
    "event_type": "bill.created",
    "client_id": "your_client_id",
    "webhook_url": "https://your-server.com/webhooks/billerapi",
    "webhook_secret": "whsec_your_signing_secret"
  }'

Related