subscriptions

Create a subscription

Create a new event subscription. You can subscribe to multiple events with a single request. You can create up to 10 webhook subscriptions per organization.

BILL provides a full catalog of all the events that you can subscribe to with GET /v3/events/catalog. See Get events catalog in the API reference for more information.

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

post/v3/subscriptions

Request

Base URL
https://gateway.stage.bill.com/connect-events
URL
https://gateway.stage.bill.com/connect-events/v3/subscriptions
Auth
none declared. Required headers: X-Idempotent-Key

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}}

Request body

namestring required

Subscription name

notificationUrlstring required

Event notification URL. The URL must be HTTPS. BILL uses this URL to send you event notifications.

Example request

{
  "name": "Bill management",
  "status": {
    "enabled": true
  },
  "events": [
    {
      "type": "bill.created",
      "version": "1"
    },
    {
      "type": "bill.updated",
      "version": "1"
    },
    {
      "type": "bill.archived",
      "version": "1"
    }
  ],
  "notificationUrl": "{{webhook_notification_url}}"
}

Response

createSubscription 200 response

idstring

BILL-generated ID of the subscription

namestring

Subscription name

organizationIdstring

BILL-generated ID of the organization. BILL sends you event notifications only for the BILL organization used to set up a subscription.

notificationUrlstring

Event notification URL. The URL must be HTTPS. BILL uses this URL to send you event notifications.

createdTimestring date-time

Subscription created date and time

updatedTimestring date-time

Subscription updated date and time

securityKeystring

BILL-generated security key.

When you create a new subscription, a one-time securityKey is generated and all event notifications sent to your notificationUrl are signed with this key.

Changes

No recorded changes to this operation across all 1 revision of this API.