Authentication

The daisyBill webhook system supports two authentication methods that work together to ensure secure delivery:

1. Basic Authentication

If you configure basic authentication credentials when setting up your webhook endpoint, daisyBill will include a Authorization header with each webhook request.

Request Headers:

Authorization: Basic <base64_encoded_credentials>

The credentials are base64-encoded in the format username:password.

2. Webhook Signature Verification

Every webhook request includes a daisybill-signature header containing an HMAC SHA256 signature. You should verify this signature to ensure the webhook request is authentic and came from daisyBill.

Request Headers:

daisybill-signature: <hmac_sha256_hex_digest>

The signature is computed as:

HMAC-SHA256(signing_secret, request_body)

Important: Always verify the webhook signature before processing the payload to prevent unauthorized requests.

CSRF Protection

Web frameworks like Rails and Django will check that every POST request contains a CSRF token. This may prevent you from receiving webhooks from daisyBill. To get past this, you will need to ignore CSRF protection for your webhook-consuming endpoints.

Duplicate Events

Your webhook endpoints might receive the same event more than once. Guard against this by keeping track of events in your system using the id property on the event.

Order of Events

daisyBill webhooks may be sent multiple times if the delivery status is considered failed. Make sure your endpoint can receive the same notification multiple times and in the wrong order.

You can fetch missing events using the events API endpoint or verify event information by issuing an API request for the related resource.

Respond Quickly

daisyBill expects a response from your endpoint within 5 seconds.