Billie

Operational trust readiness - UAT/demo disclosure

Webhook documentation

How Billie partners should verify signed webhook deliveries, handle retries, prevent replay, and subscribe to payment, payout, refund, and bill events.

Signature verification

Billie signs each delivery with HMAC-SHA256 using the endpoint secret. Partners verify the X-Billie-Signature header against the exact request body before parsing or acting on the event.

Timestamp tolerance

The X-Billie-Timestamp header is expected to be within five minutes of the receiver clock. Events outside that tolerance should be rejected and reviewed for clock drift or replay risk.

Replay prevention

Store each event id and signature timestamp for at least 24 hours. Reject duplicate event ids for the same endpoint, and keep idempotent handlers for payment, payout, refund, and bill state changes.

Retry schedule

Billie treats 2xx responses as delivered. Transient failures are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours before moving the delivery to manual support review.

Event catalogue

payment.succeeded

Sent when a customer payment reaches a final successful state and the merchant or biller can fulfil the paid item.

{
  "id": "evt_payment_01",
  "type": "payment.succeeded",
  "data": {
    "amount": "25.50",
    "currency": "USD",
    "paymentId": "pay_24091",
    "status": "SUCCEEDED"
  }
}

payout.paid

Sent when an approved payout is marked paid after finance and settlement controls complete.

{
  "id": "evt_payout_01",
  "type": "payout.paid",
  "data": {
    "amount": "120.00",
    "currency": "USD",
    "payoutId": "po_1042",
    "status": "PAID"
  }
}

refund.created

Sent when a refund request is created and queued for review, approval, or downstream rail processing.

{
  "id": "evt_refund_01",
  "type": "refund.created",
  "data": {
    "amount": "10.00",
    "currency": "USD",
    "paymentId": "pay_24091",
    "refundId": "rf_3381"
  }
}

bill.published

Sent when a biller publishes a bill that is ready for customer notification or account lookup.

{
  "id": "evt_bill_01",
  "type": "bill.published",
  "data": {
    "accountReference": "METER-2002",
    "billId": "bill_2026_0041",
    "dueDate": "2026-07-31"
  }
}