BILL webhook API general rules
The BILL webhook API follows a set of rules.
Access rules
Design | Description |
---|---|
Base URL | https://gateway.stage.bill.com/connect-events |
Security key | When 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 . |
Authentication rules
Both organization-level users and partner users can set up webhooks. Simply set the required header values in your webhook API requests and you have access to webhooks at the desired level.
Organization-level header values for webhooks | Partner-level header values for webhooks |
---|---|
sessionId API session ID generated with /v3/login | sessionId Partner API session ID generated with /v3/partner/login |
devKey Developer key sent to you by BILL when you create a developer account | appKey Application key sent to you by BILL when you create a partner account |
Idempotent key rules
An API request is idempotent when the response shows the same result each time the same request is made.
Design | Description |
---|---|
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-key This ensures that you do not accidentally create multiple subscriptions or security keys for the same set of events. |
X-Idempotent-Key header 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. |
Idempotent key errors
Incorrect usage of the idempotent key results in errors.
Error | HTTP status |
---|---|
Missing idempotent key | 400 Bad Request |
Malformed idempotent key | 400 Bad Request |
The same idempotent key is used for different operations | 409 Conflict |
Additional requests are made with the same idempotent key when another request is in progress | 429 Too Many Requests |
Updated 2 months ago