Skip to content
Esc
↑↓navigate↵open⌘Jpreview

Create a webhook

POST/webhooks
Authorization
AuthorizationBearer token · headerrequired

A BillionSend API key (bs_…).

Request body
requiredapplication/json
endpointstring<uri>required
max length 2048
eventsstring[]required
min items 1
inbox_idsstring<uuid>[] | null

BillionSend extension: inbox events and email.received reach this endpoint only for these inboxes of the team (at most 100). null means every inbox. Omitted: every inbox.

max items 100
signing_secretstring

Signing secret to use instead of minting one: whsec_ followed by base64 of 24-64 bytes (the Standard Webhooks format). An existing secret carried over keeps the receiver verifying unchanged; when omitted, a new one is generated.

Responses
200

Webhook created; signing_secret is also retrievable via GET /webhooks/{id}

objectstringrequired
Allowed:webhook
idstring<uuid>required
signing_secretstringrequired
401

Missing, malformed, unknown or revoked API key

statusCodenumberrequired
namestringrequired
messagestringrequired
403

Plan webhook endpoint limit reached

statusCodenumberrequired
namestringrequired
messagestringrequired
422

Validation error

statusCodenumberrequired
namestringrequired
messagestringrequired
429

Over the rate limit (rate_limit_exceeded, with Retry-After)

statusCodenumberrequired
namestringrequired
messagestringrequired
Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST 'https://api.billionsend.com/webhooks' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoint": "http://example.com",
  "events": [
    "email.scheduled"
  ],
  "inbox_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "signing_secret": "string"
}'
Response
{
  "object": "webhook",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "signing_secret": "string"
}

Was this page helpful?