Webhook API general rules

Sandbox base URL

https://gateway.stage.bill.com/connect-events

Production base URL

https://gateway.prod.bill.com/connect-events

Security

When you create a new subscription, a one-time securityKey is one of the generated values in the response. BILL uses the HMAC-SHA256 algorithm to sign all event notifications sent to your notificationUrl with the securityKey. The output format of the generated hash value is base64.

The generated hash is sent as the x-bill-sha-signature header value with all event notifications. With this value, you can verify that each notification sent to you is from BILL.

Keep the security key for your subscription updated in a timely manner. Generate a new security key for your subscription with POST /v3/subscriptions/{subscriptionId}/security-key.

See Test with BILL webhook security for more information.

Endpoints that require an idempotent key

Only two BILL webhook endpoints require an idempotent key.

• Create a subscription: POST /v3/subscriptions
• Create a security key: POST /v3/subscriptions/{subscriptionId}/security-keyThis ensures that you do not accidentally create multiple subscriptions or security keys for the same set of events.

X-Idempotent-Keyheader value

The idempotent key is set as an additional X-Idempotent-Key header value. You must generate a new idempotent key for each new request.

Time To Live (TTL)

For an idempotent key used in an API request, the API response is cached for 24 hours.

For this duration, if your API request results in a successful response, and then you make another API request with the same X-Idempotent-Key header value, you will receive the cached response from your previous API request.

If your API request results in an error, and then you use the same X-Idempotent-Key header value with your fixed API request, you will continue to receive the cached error response from your previous API request. In this case, you must send a new X-Idempotent-Key header value with your fixed API request for a successful response.

UUID4 format

All your idempotent keys must be in the UUID4 format.

UUID4 is a randomly-generated 128-bit identifier. You can easily generate a value for your integration. For example, in Python, you can generate a UUID4 value with uuid.uuid4().

Errors

Incorrect usage of the idempotent key results in errors. See the next section for more information about idempotent key errors. When you receive an idempotent key error, fix the problem at your end and retry.