Skip to main content
POST
Create a webhook subscription

Authorizations

Authorization
string
header
required

Your workspace API key, sent as Authorization: Bearer blu_.... Workspace admins can find it in the Blujay app under API.

An API key has full access to your workspace and works on every endpoint. There is no test mode: every key sends real messages and changes real data, so keep it secret and use it only from your server.

Each API key can make 600 read requests and 120 write requests per minute, plus 60 attachment requests per minute. Over a limit you get 429 RATE_LIMIT_EXCEEDED with Retry-After.

Body

application/json
url
string<uri>
required

Your HTTPS endpoint, up to 2,048 characters. It must resolve to a public address; localhost and private, link-local and cloud metadata addresses are rejected.

Maximum string length: 2048
Example:

"https://example.com/webhooks/blujay"

event_types
enum<string>[]
required

The events to send to this endpoint (1–100).

Required array length: 1 - 100 elements

Events you can subscribe to.

  • Outbound message events (message.sent, message.delivered, message.read, message.failed) cover messages sent through Blujay: the app, workflows, scheduled sends, integrations and the API. message.accepted is sent only for API sends. Messages sent outside Blujay aren't included.
  • message.received covers new incoming direct and group messages, not older messages Blujay imports later.
  • phone_number.status_updated is currently sent only when one of your numbers is replaced by a new dedicated number: the old number becomes unavailable and the new one active.
Available options:
message.accepted,
message.sent,
message.delivered,
message.read,
message.failed,
message.received,
reaction.added,
reaction.removed,
phone_number.status_updated,
contact.tag_added,
contact.assigned,
chat.typing_indicator.started,
chat.typing_indicator.stopped,
participant.added,
participant.removed,
chat.group_name_updated,
message.edited,
message.unsent
phone_number_filter
object

Which of your numbers this subscription gets events for. all covers every number, including numbers you add later; selected covers only the phone_number_ids you list. Contact events are always sent for the whole workspace. Defaults to all on create; left unchanged on update if you omit it.

webhook_version
enum<string>
default:2026-10-03

The payload version for this subscription's events. When omitted, new subscriptions use 2026-10-03, which adds iMessage group typing with participants and otherwise matches 2026-09-02. Existing subscriptions keep their version until you change it.

Available options:
2026-06-14,
2026-08-01,
2026-08-20,
2026-09-02,
2026-10-03
status
enum<string>
default:active

Defaults to active. A disabled subscription doesn't receive new events.

Available options:
active,
disabled

Response

The new subscription, including its signing_secret.

Wraps every successful response. The result is in data.

status
enum<string>
required
Available options:
success
trace_id
string
required
Pattern: ^trc_[A-Za-z0-9_-]+$
Example:

"trc_8f2a1c0e4b7d"

timestamp
string<date-time>
required
Example:

"2026-10-14T17:01:00.000Z"

data
object
required
client_request_id
string

Your X-Request-ID header value, echoed back when you send one. Not included on the send responses (POST /v1/chats, POST /v1/chats/{chat_id}/messages, POST /v1/messages/{message_id}/retry); keep your own mapping from your request ID to the returned message ID there.