BILL webhook API general rules

The BILL webhook API follows a set of rules.

Access and authentication rules

DesignDescription
Base URLhttps://gateway.stage.bill.com/connect-events
AuthenticationThe BILL webhook service requires sessionId and devKey header values for authentication just like with any other BILL API endpoint. See API sandbox sign in for more information about generating a sessionId.
Security keyWhen you create a new subscription, a one-time securityKey is one of the generated values in the response. All event notifications sent to your notificationUrl are signed with this key using the HMAC-SHA256 algorithm. The key is sent as the x-bill-sha-signature header value in the notification.

You can use the security key to verify all notifications sent to you. It is good practice to keep the security key for your subscription updated in a timely manner. You can generate a new security key for your subscription with POST /v3/subscriptions/{subscriptionId}/security-key.

Idempotent key rules

An API request is idempotent when the response shows the same result each time the same request is made.

DesignDescription
Endpoints that require an idempotent keyOnly 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-Key header valueThe 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 formatAll 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().
ErrorsIncorrect 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.

Idempotent key errors

Incorrect usage of the idempotent key results in errors.

ErrorHTTP status
Missing idempotent key400 Bad Request
Malformed idempotent key400 Bad Request
The same idempotent key is used for different operations409 Conflict
Additional requests are made with the same idempotent key when another request is in progress429 Too Many Requests