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.

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