Webhooks

Use BILL webhooks to subscribe to and receive real-time notifications for events, such as create a vendor, update a vendor, or create a payment. In addition, as a BILL partner, when you create a subscription for events, you get event notifications for all your created organizations.

Tutorial: BILL v3 API webhooks explained

When you subscribe to BILL events, you provide a location URL for where you want to receive notifications. BILL sends a notification to that URL each time a subscribed event is triggered.

BILL webhooks best practice

While the BILL webhooks work as expected, we recommend that webhook notifications should not be treated as the only source of truth. For critical workflows, we recommend validating data with the GET API operations for accuracy and consistency.

BILL webhooks as a trigger

Use BILL webhooks as a trigger for your system to learn that an entity has changed.

Validate data with API

Validate data with the GET API operation for the entity. For example, when you receive a vendor.updated notification, validate with GET /v3/vendors/{vendorId}.

Handle duplicate notifications

Maintain an idempotent system that is able to safely handle duplicate event notifications.

Periodic reconciliation

Set up a cadence (for example, weekly or daily) for data reconciliation. In case a webhook is delayed or missed, your system can detect and fix any drift with the API.

More documentation

In the next set of sections, we walk through the rules for working with BILL webhooks.

Section	Description
Webhook API general rules	Access rules, authentication rules, and idempotent key rules
Webhook API notification rules	BILL webhook notifications for events follow a set of rules
Webhook Events and Subscriptions	Subscribe to BILL events, generate a test event notification, and get events for a subscription
Test with BILL webhook security	Steps for validating the BILL webhook security measures
Webhook API error responses	For error responses, BILL sends an HTTP status code depending on the error

In addition, we list examples of the BILL webhook events and notification payloads in the Notification payloads reference.

Event	Related documentation
`vendor.created` `vendor.updated` `vendor.archived` `vendor.restored`	Vendor notification payloads
`autopay.failed`	Vendor auto-pay notification payload
`bill.created` `bill.updated` `bill.archived` `bill.restored`	AP bill notification payloads
`payment.updated` `payment.failed`	AP payment notification payloads
`bank-account.created` `bank-account.updated`	Bank account notification payloads
`card-account.created` `card-account.updated`	Card account notification payloads
`invoice.created` `invoice.updated` `invoice.archived` `invoice.restored`	AR invoice notification payloads
`risk-verification.updated`	Risk verification notification payload
`spend.transaction.updated`	Spend & Expense transaction notification payload
`spend.reimbursement.created` `spend.reimbursement.updated` `spend.reimbursement.deleted`	Spend & Expense reimbursement notification payload
`spend.three-ds-challenge.created`	Spend & Expense 3D Secure challenge notification payload