BILL webhook API notification rules

Event notifications from the BILL webhook API follow a set of rules.

Notification URLThe notification URL is the location where you receive event notifications. The URL that you provide must be HTTPS.

Note: When you are testing with BILL webhooks, you can use an online service for setting up a notification URL. For example,
All notifications are organization-specificBILL sends you event notifications only for the BILL organization used to set up a subscription.

When you set up a subscription, the organizationId in the API response represents the BILL organization for which your subscription is created. See Working with BILL webhooks for more information.
Event notification idBILL sends each event notification with a unique event id. Your integration must save event id value to avoid processing any duplicate notifications.
JSON escaped payloadWhen BILL sends you an event notification, the payload is JSON-escaped and is presented as a string.

Ensure that your integration handles JSON escaped payloads for notifications. See Working with BILL webhooks for more information about a sample payload.
Order of notificationsIn case notifications are sent out of order, organize the notifications based on the timestamp of each notification.
Notification retriesWhen BILL does not receive a HTTP 200 statusCode for an event notification within 10 seconds, the notification is considered a failure.

When an event notification fails, BILL tries to send the notification again with exponential backoff. When BILL does not receive a HTTP 200 statusCode after resending a notification five times, BILL sends the notification in a Dead-Letter Queue (DLQ) and handles notification retries at a later time.

To address any issues with notification retries, you can get the list of event notifications sent to you for a subscription with GET /v3/events/subscription/{subscription_id}.