v1

latestOpenAPI 3.0.12026-07-24310590875.6 KB

subscriptions

Create a security key

Create a new security key for your subscription.

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 use this endpoint to generate a new security key based on your desired frequency.

See Webhooks in the Guides section for more information, sample requests, and notification payloads for BILL events.

post/v3/subscriptions/{subscriptionId}/security_key

Path parameters

subscriptionIdstring required

BILL-generated ID of the subscription

Example:{{webhook_subscription_id}}

Headers

X-Idempotent-Keystring required

Idempotency key. The key must be in the UUID4 format.

sessionIdstring nullable

API session ID generated with /v3/login

Example:{{session_id}}

devKeystring nullable

Developer key sent to you by BILL when you create a developer account. Set sessionId and devKey for organization-level BILL v3 API webhook events.

Example:{{developer_key}}

appKeystring nullable

Application key sent to you by BILL when you create a partner account. Set sessionId and appKey for partner-level BILL v3 API webhook events.

Example:{{app_key}}

apiTokenstring nullable

Access token for Spend & Expense API authentication. Set apiToken for Spend & Expense webhook events.

Example:{{api_token}}

Response

createNewSecurityKey 200 response

securityKeystring

BILL-generated security key