Bird Webhooks API
Webhook endpoint management.
Bird Webhooks API is one of 65 APIs that Bird publishes on the APIs.io network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification.
Tagged areas include Webhook. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an API reference, and an AsyncAPI specification.
This API exposes 15 operations across 8 paths, and defines 220 schemas. It is described by OpenAPI 3.2.0, at version 1.0.
Requests are made against 5 base URLs: https://{region}.platform.bird.com, https://platform.bird.com, http://localhost:8080, https://conversations.messagebird.com/v1, https://voice.messagebird.com.
15 operations
8 paths
220 schemas
2 DELETE5 GET2 PATCH5 POST1 PUT
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 5
Bird Webhooks API declares
5 security schemes
for authenticating requests.
It accepts HTTP bearer tokens (BearerAuth).
An API key is passed in the cookie as bird_session (CookieAuth).
An API key is passed in the header as X-Realtime-Key (RealtimeKey).
An API key is passed in the header as X-Realtime-Secret (RealtimeSecret).
An API key is passed in the header as Authorization (accessKey).
BearerAuth— Pass the API key as a bearer token in the Authorization header. Keys use the format bk{region}. The prefix identifies the region and selects the API endpoint.…CookieAuth— Session cookie set after signing in to the Bird dashboard. The cookie value is an opaque session token; no session data is stored in the cookie itself.RealtimeKey— The Realtime app key. Together with X-Realtime-Secret, it authenticates a request to the Realtime API in addition to the workspace credential. Both values come…RealtimeSecret— The Realtime app secret paired with X-Realtime-Key. The API returns the secret only when the key is created and does not store it. Create a new key and revoke…accessKey— Access key authentication in the form of 'AccessKey {accessKey}'.
Paths & Operations 15
Across 8 paths, the API surfaces 15 operations — 2 DELETE, 5 GET, 2 PATCH, 5 POST, 1 PUT. Each is listed below with its method, path, parameters, and response codes.
Webhooks 15
Webhook endpoint management.
POST
/v1/webhooks
Create a webhook endpoint
GET
/v1/webhooks
List webhook endpoints
GET
/v1/webhooks/{webhook_id}
Get a webhook endpoint
PATCH
/v1/webhooks/{webhook_id}
Update a webhook endpoint
DELETE
/v1/webhooks/{webhook_id}
Delete a webhook endpoint
POST
/v1/webhooks/{webhook_id}/rotate-secret
Rotate webhook signing secret
POST
/v1/webhooks/{webhook_id}/test
Test a webhook with a sample event
POST
/v1/webhooks/{webhook_id}/replay
Replay failed deliveries
GET
/v1/webhooks/{webhook_id}/attempts
List delivery attempts
GET
/webhooks
List webhooks
POST
/webhooks
Create a webhook
GET
/webhooks/{webhookId}
View a webhook
PATCH
/webhooks/{webhookId}
Update a webhook
DELETE
/webhooks/{webhookId}
Delete a webhook
PUT
/webhooks/{webhookId}
Update a voice webhook
Schemas 220
The contract defines 220 schemas that model the data the API accepts and returns. The most detailed are EventEmailMailboxMessageReceivedData (14 properties), EventEmailReceivedData (12 properties), EventSMSBase (12 properties), ErrorBody (11 properties). Each schema is shown below with its type and property counts.
_ListEnvelope
object
3 properties
3 required
SMSSegments
object
Segment breakdown for the message body. Segment count drives billing.
3 properties
3 required
WhatsAppMessageID
string
WhatsAppFileID
string
EventEmailMailboxMessageReceivedData
object
Identifiers, threading details, authentication results, and extracted text for a received mailbox message. The thread-message endpoints provide the original so…
14 properties
7 required
EventWhatsAppDelivered
object
The message was delivered to the recipient's device.
3 properties
3 required
ErrorDetail
object
2 properties
2 required
ContactID
string
SMSError
objectnull
Failure detail for a message that could not be delivered or was rejected.
4 properties
3 required
EventWhatsAppBase
object
Identity fields shared by every WhatsApp lifecycle event payload.
8 properties
7 required
EventWhatsAppReceivedData
object
Payload of the whatsapp.received event. Carries the message's content so a subscriber can act on it without reading the message back.
EmailBounceType
string
Bounce classification. - hard: A permanent failure, such as an invalid address or a domain that does not exist. - soft: A transient failure, such as a full mai…
EventPreferenceRevoked
object
A stated preference was revoked (a person opted out, or a customer wrote a revoke) and became the key's live statement.
3 properties
3 required
WebhookReplayRequest
object
2 properties
EventVerifyAttemptUndeliveredData
object
Payload of the verify.attempt.undelivered event.
WhatsAppContactOrg
object
Where the contact works, as their card records it.
3 properties
VoiceCallStatus
string
Call status. A call that has ended carries one of: - answered means it connected and the far end picked up. - noanswer means nobody picked up before the call t…
SuppressionID
string
VoiceCallID
string
WhatsAppAddress
object
Sender or recipient of a WhatsApp message: a phone number, a business-scoped user ID, or both. A message received from a WhatsApp user carries whatever profile…
5 properties
EventSMSRejected
object
The API rejected the message before sending it to the carrier because of an invalid destination, suppression, or content or policy restriction.
3 properties
3 required
EventEmailListUnsubscribedData
object
Payload of the email.listunsubscribed event.
WhatsAppGroupID
string
EventEmailOutOfBandBounce
object
A bounce notification arrived after the message had already been accepted for delivery. Fires once per recipient.
3 properties
3 required
EventPreferenceDeleted
object
A stated preference was deleted, superseding it in the ledger without erasing its history.
3 properties
3 required
EventWhatsAppAcceptedData
object
Payload of the whatsapp.accepted event.
PreferenceDeletedEventType
string
Always preference.deleted for this event.
EventEmailScheduledData
object
Payload of the email.scheduled event.
EventSMSBase
object
Identity fields shared by every SMS lifecycle event payload.
12 properties
11 required
EventEmailMailboxMessageSent
object
A mailbox message was handed off for delivery. This event fires once per message. The same send also emits per-recipient email. events. Choose one event family…
3 properties
3 required
SMSSuppressionReason
string
Reason this sender cannot message the subscriber: - keywordstop: The subscriber sent a stop keyword. A start keyword clears it. - carrieroptedout: The carrier…
WhatsAppInteractiveQuickReplyButton
object
A reply button's label and the handle it carries back. On the echo of a message Bird sent, the pair the send declared; on an inbound interactivereply, the pair…
2 properties
2 required
EventWhatsAppRejectedData
object
Payload of the whatsapp.rejected event.
EventEmailRejectedData
object
Payload of the email.rejected event.
MessageCost
objectnull
What was charged for a message, split into the components that make it up. null until at least one component has been priced.
4 properties
4 required
Tag
object
Structured key/value label attached to a message or a call. Use tags for low-cardinality filtering dimensions (category, experiment ID, template ID); they surf…
2 properties
2 required
EventEmailMailboxMessageFailedData
object
Payload of the emailmailbox.messagefailed event.
4 properties
4 required
EventEmailBouncedData
object
Payload of the email.bounced event.
EventDomainVerifiedData
object
Payload of the domain.verified event.
3 properties
3 required
EventVerifyVerificationFailedData
object
Payload of the verify.verification.failed event.
EventEmailCanceled
object
A scheduled send was canceled before it fired. Fires once for each message regardless of its recipient count.
3 properties
3 required
EventEmailOpenedData
object
Payload of the email.opened event.
WhatsAppContactAddress
object
One postal address on a shared contact card.
7 properties
EventEmailUnsubscribedData
object
Payload of the email.unsubscribed event.
EventWhatsAppReadData
object
Payload of the whatsapp.read event.
EventSMSDeliveredData
object
Payload of the sms.delivered event.
EventVoiceCallEnded
object
The call ended after either party hung up or call setup failed.
3 properties
3 required
WhatsAppLocation
object
Location content of a WhatsApp message: a point on the map the recipient can open in their maps app.
5 properties
EventEmailClickedData
object
Payload of the email.clicked event.
EventEmailMailboxMessageFailed
object
A mailbox message reached a terminal delivery failure. This event fires once per message. The same send also emits per-recipient email. events. Choose one even…
3 properties
3 required
EmailBroadcastID
string
WhatsAppReactedEventType
string
Always whatsapp.reacted for this event.
EventWhatsAppFailedData
object
Payload of the whatsapp.failed event.
EventVoiceCallAnswered
object
The called party answered and media began flowing.
3 properties
3 required
EventDomainFailed
object
A sending domain failed DNS verification.
3 properties
3 required
EventVoiceCallEndedData
object
Payload of the voicecall.ended event.
EventWhatsAppFailed
object
Message delivery failed permanently.
3 properties
3 required
EventSMSExpired
object
The message's validity period elapsed before it could be delivered.
3 properties
3 required
EventVerifyVerificationVerified
object
The verification was successfully resolved: the recipient confirmed the correct code.
3 properties
3 required
EventSMSUndelivered
object
The carrier reported a non-permanent failure to deliver the message.
3 properties
3 required
RecipientRole
string
Envelope position of a recipient on an outbound email event.
WhatsAppDocument
object
Document content of a WhatsApp message.
EventWhatsAppReactedData
object
Payload of the whatsapp.reacted event. Names the message the contact reacted to, not the reaction, because a reaction is an annotation on a message rather than…
5 properties
5 required
EventEmailMessageBase
object
Identity fields shared by the message-level email lifecycle events (scheduled, canceled), which are not tied to a single recipient.
4 properties
4 required
EventPreferenceDeletedData
object
Payload of the preference.deleted event.
ErrorBody
object
11 properties
6 required
SMSSuppressionCreatedEventType
string
Always smssuppression.created for this event.
WhatsAppSuppressionCreatedEventType
string
Always whatsappsuppression.created for this event.
EventSMSFailedData
object
Payload of the sms.failed event.
VerificationTo
object
The recipient to verify. Provide an email, a phonenumber, or both; at least one is required. The addresses also identify the verification: a check must supply…
2 properties
WhatsAppUnsupported
object
A message whose content we do not model, named so it is visible in the message log rather than arriving empty. Inbound only.
1 property
1 required
EventVerifyVerificationFailed
object
The verification ended without the recipient receiving a passcode: every planned channel reported that its send would not arrive.
3 properties
3 required
VoiceCallDirection
string
Whether the call originated from your PBX (outbound) or arrived from a remote party (inbound).
EventSMSRejectedData
object
Payload of the sms.rejected event.
WebhookEvent
Webhook delivery body. type identifies the event variant, timestamp is when the event occurred, and data contains the event-specific payload. See the [webhooks…
InboundEmailMessageID
string
EventEmailListUnsubscribed
object
Recipient unsubscribed via the RFC 8058 one-click List-Unsubscribe mechanism. Fires once per recipient.
3 properties
3 required
WhatsAppSuppressionID
string
EventVerifyAttemptSent
object
A one-time passcode was dispatched to the recipient on a channel.
3 properties
3 required
WhatsAppContactEmail
object
One email address on a shared contact card.
2 properties
EventEmailCanceledData
object
Payload of the email.canceled event.
WhatsAppInteractiveReplyType
string
Which kind of tap the reply came from. - button: a reply button on an interactive message, or a quick-reply button on a template. Both carry an identifier and…
WhatsAppImage
object
Image content of a WhatsApp message.
EventEmailSuppressionCreatedData
object
Payload of the emailsuppression.created event.
4 properties
4 required
_ListEnvelopeWithTotal
WebhookEndpointCreate
object
3 properties
2 required
EventEmailReceivedData
object
Payload of the email.received event.
12 properties
6 required
EventEmailOpened
object
The recipient opened the email (the tracking pixel was loaded). May fire more than once per recipient.
3 properties
3 required
EventEmailRejected
object
The API rejected the email before delivery because of suppression, transmission failure, content, or policy. Fires once per recipient.
3 properties
3 required
EventVerifyVerificationCreated
object
A verification session was created and its first one-time passcode is being sent.
3 properties
3 required
EventEmailProcessedData
object
Payload of the email.processed event.
EventSMSExpiredData
object
Payload of the sms.expired event.
EventVerifyBase
object
Identity fields shared by every Verify lifecycle event payload.
4 properties
4 required
SMSReceivedEventType
string
Always sms.received for this event.
EventPreferenceGrantedData
object
Payload of the preference.granted event.
EventEmailDeferredData
object
Payload of the email.deferred event.
EmailID
string
VerificationAttemptFailureReason
string
Why a passcode send did not deliver: - carrierrejected: The SMS carrier rejected the send. - hardbounce: The email permanently bounced. - softbounce: The email…
SMSTemplateContentHash
string
A fingerprint of SMS template text, prefixed with its algorithm. Compare it within this API version to identify the exact source without transferring it.
EventSMSSent
object
The API handed the message to the carrier for delivery.
3 properties
3 required
VerificationChannel
string
The channel a passcode is delivered over. Open enum: new channels may be added over time, so treat any unrecognized value as a future channel rather than an er…
WhatsAppInteractiveListRow
object
One option in a list's menu. On the echo of a message Bird sent, the row as declared; on an inbound interactivereply, the row the contact chose. No length is d…
3 properties
2 required
EventEmailReceived
object
The API received and parsed an inbound email. The payload carries the message's identifiers, sender and recipients, subject, threading reference, and authentic…
3 properties
3 required
WebhookEndpointList
SMSTemplateID
string
EventEmailAccepted
object
The API accepted the email send and is preparing it for delivery. Fires once per requested recipient.
3 properties
3 required
EventPreferenceGranted
object
A stated preference was granted (a person consented, or a customer wrote a grant) and became the key's live statement.
3 properties
3 required
EventEmailMailboxMessageSentData
object
Payload of the emailmailbox.messagesent event.
3 properties
3 required
WhatsAppErrorCode
string
Standardized failure reason: - insufficientbalance: The workspace wallet could not fund the send. - pricenotfound: No price was configured for the destination…
EventWhatsAppSuppressionCreatedData
object
Payload of the whatsappsuppression.created event.
5 properties
5 required
EventVerifyAttemptDeliveredData
object
Payload of the verify.attempt.delivered event.
WebhookAttempt
object
9 properties
7 required
SMSTemplateVersionID
string
EventSMSReceived
object
A message was received on one of your numbers.
3 properties
3 required
EventSMSAccepted
object
The API accepted the SMS send request and queued it for processing.
3 properties
3 required
WebhookEndpointCreated
EventWhatsAppAccepted
object
The API accepted and charged the send request.
3 properties
3 required
WebhookAttemptList
object
1 property
1 required
WorkspaceID
string
SMSErrorCode
string
Standardized failure reason: - invaliddestination: The number is unassigned, ported out, or malformed. - unreachable: The handset is off or outside coverage. -…
EventSMSReceivedData
object
Payload of the sms.received event.
EventSMSAcceptedData
object
Payload of the sms.accepted event.
CurrencyCode
string
ISO 4217 three-letter currency code.
WhatsAppInteractiveReply
object
What the contact tapped, on an inbound message answering an interactive message or a template's quick-reply button. type names the kind and the field it names…
3 properties
1 required
EventVerifyVerificationCreatedData
object
Payload of the verify.verification.created event.
NextAction
object
5 properties
2 required
Timestamps
object
2 properties
2 required
RecipientID
string
EventEmailAcceptedData
object
Payload of the email.accepted event.
EventEmailDelivered
object
An outbound email reached the recipient's mail server and was accepted.
3 properties
3 required
WebhookRotateSecretResponse
object
1 property
1 required
VerificationTerminalReason
string
Why a verification session reached its final state without succeeding: attemptsexhausted (too many incorrect passcodes), ttlelapsed (the time window elapsed be…
EventWhatsAppReacted
object
A contact placed, changed or took back a reaction on a message.
3 properties
3 required
WhatsAppVideo
object
Video content of a WhatsApp message.
EventEmailMailboxThreadCreated
object
A new thread was created in a mailbox, from either direction.
3 properties
3 required
EventEmailMailboxThreadCreatedData
object
Payload of the emailmailbox.threadcreated event.
4 properties
4 required
WhatsAppContactName
object
The contact's name, in the parts their device supplied. Every part is optional: WhatsApp sends what the card holds and omits the rest.
6 properties
VerifyVerificationFailedEventType
string
Always verify.verification.failed for this event.
EventEmailComplained
object
The recipient marked the email as spam through their mailbox provider's feedback loop. Fires once per recipient.
3 properties
3 required
ThreadID
string
EventSMSUndeliveredData
object
Payload of the sms.undelivered event.
EventEmailDeliveredData
object
Payload of the email.delivered event.
EventPreferenceBase
object
Identity fields shared by every preference lifecycle event: the key plus the ledger entry the write appended. effectiveat is not repeated here: it is the envel…
8 properties
8 required
EmailRejectionReason
string
Why an email was rejected before delivery. - recipientsuppressed: The recipient is on the workspace suppression list, so delivery was never attempted. - transm…
EventVoiceCallInitiated
object
Call routing began.
3 properties
3 required
WhatsAppReceivedEventType
string
Event type.
WebhookEventID
string
EventWhatsAppRejected
object
The API rejected the message before sending it to WhatsApp because the recipient is on the workspace suppression list, the wallet has insufficient balance, or…
3 properties
3 required
WebhookEndpointID
string
VerificationID
string
WebhookTestResponse
object
6 properties
3 required
PreferenceTransitionID
string
EventEmailUnsubscribed
object
Recipient unsubscribed by clicking a tracked unsubscribe link in the email. Fires once per recipient.
3 properties
3 required
EventEmailMailboxSuspendedData
object
Payload of the emailmailbox.suspended event.
2 properties
2 required
MailboxID
string
EventEmailComplainedData
object
Payload of the email.complained event.
PreferenceChannel
string
The channel a preference statement applies to. A preference addresses one channel: the handle that identifies the person differs per channel, so opting out of…
WhatsAppContactCard
object
A contact card on this message: one the contact shared, or one this workspace sent. Nothing here is required. WhatsApp sends the parts the card holds and omits…
9 properties
SortOrder
string
Sort direction, ascending or descending.
EventEmailMailboxMessageDeliveredData
object
Payload of the emailmailbox.messagedelivered event.
3 properties
3 required
WebhookTestRequest
object
1 property
EventWhatsAppRead
object
The recipient read the message.
3 properties
3 required
SMSMessageID
string
EventWhatsAppSentData
object
Payload of the whatsapp.sent event.
PreferenceGrantedEventType
string
Always preference.granted for this event.
EventEmailBase
object
Identity fields shared by every email lifecycle event payload.
8 properties
8 required
EventVerifyAttemptDelivered
object
The channel confirmed delivery of a one-time passcode to the recipient.
3 properties
3 required
EventWhatsAppSuppressionCreated
object
An address was added to the workspace's WhatsApp suppression ledger.
3 properties
3 required
PreferenceCoverage
string
How much traffic the statement covers. nontransactional covers marketing and other non-essential messages while transactional messages such as receipts and ver…
EventVerifyAttemptSentData
object
Payload of the verify.attempt.sent event.
EventVoiceCallAnsweredData
object
Payload of the voicecall.answered event.
WhatsAppError
objectnull
Failure detail for a message that could not be delivered or was rejected.
4 properties
3 required
WhatsAppContactUrl
object
One website on a shared contact card.
2 properties
WhatsAppSticker
object
Sticker content of a WhatsApp message.
EventEmailDeferred
object
The recipient's mail server temporarily refused the email. Delivery remains pending and is retried. May fire more than once per recipient.
3 properties
3 required
PreferenceRevokedEventType
string
Always preference.revoked for this event.
EventVoiceBase
object
Identity fields shared by every voice call lifecycle event payload.
6 properties
5 required
EventEmailMailboxMessageReceived
object
An email arrived in a mailbox. The same message also emits an email.received event. The two events can arrive in either order. Choose one event family for each…
3 properties
3 required
EventPreferenceRevokedData
object
Payload of the preference.revoked event.
EventSMSFailed
object
Message delivery failed permanently.
3 properties
3 required
EventDomainVerified
object
A sending domain completed DNS verification successfully.
3 properties
3 required
WhatsAppContactPhone
object
One phone number on a shared contact card.
2 properties
EventSMSSentData
object
Payload of the sms.sent event.
EventWhatsAppReceived
object
A contact sent the business a WhatsApp message.
3 properties
3 required
WebhookEndpoint
EventDomainFailedData
object
Payload of the domain.failed event.
4 properties
3 required
EventVoiceCallInitiatedData
object
Payload of the voicecall.initiated event.
EventSMSDelivered
object
The carrier confirmed delivery of the message to the recipient handset.
3 properties
3 required
PreferenceID
string
EventSMSSuppressionCreatedData
object
Payload of the smssuppression.created event.
5 properties
5 required
EventSMSSuppressionCreated
object
A destination was added to the workspace's SMS suppression ledger: a subscriber's STOP, a carrier opt-out, or a manual add.
3 properties
3 required
WhatsAppText
object
Text content of a WhatsApp message.
1 property
1 required
EventVerifyAttemptUndelivered
object
A one-time passcode failed to deliver to the recipient.
3 properties
3 required
EventWhatsAppSent
object
The API handed the message to Meta for delivery.
3 properties
3 required
EventEmailMailboxMessageDelivered
object
Every recipient of a mailbox message reached a delivered state. This event fires once per message. The same send also emits one email.delivered event for each…
3 properties
3 required
WhatsAppMedia
object
Fields shared by every media content object on a WhatsApp message.
3 properties
WebhookEndpointUpdate
object
4 properties
EventEmailProcessed
object
The API prepared the message for delivery to the recipient's mail server. Fires once per recipient.
3 properties
3 required
Error
object
1 property
1 required
EventEmailBounced
object
An outbound email permanently failed at the recipient's mail server. Fires once per recipient.
3 properties
3 required
DomainID
string
EventEmailOutOfBandBounceData
object
Payload of the email.outofbandbounce event.
EventWhatsAppDeliveredData
object
Payload of the whatsapp.delivered event.
EventEmailSuppressionCreated
object
An email address was added to the workspace's suppression list (manually, via complaint, or via hard bounce).
3 properties
3 required
LanguageTag
string
A language tag in BCP-47 form, for example en or pt-BR.
SMSSuppressionID
string
EventEmailMailboxSuspended
object
This mailbox-suspension event is reserved and is not currently emitted.
3 properties
3 required
EventEmailScheduled
object
The API accepted an email scheduled for a future time. Fires once per message when the schedule is created.
3 properties
3 required
EventEmailClicked
object
The recipient clicked a tracked link in the email. May fire more than once per recipient.
3 properties
3 required
WebhookSortField
string
Field to sort webhook endpoints by: createdat (the default; newest first with the default order) or url.
WebhookEventType
string
Webhook event type. This is an open enum, so accept unrecognized values in deliveries. Subscribing to a type outside the event catalog returns a 422.
VoiceSessionID
string
EventVerifyVerificationVerifiedData
object
Payload of the verify.verification.verified event.
WhatsAppAudio
object
Audio content of a WhatsApp message.
WebhookList
object
5 properties
Webhook
object
7 properties
WebhookCreate
object
3 properties
3 required
VoiceWebhookCreate
object
2 properties
1 required
VoiceWebhookResponse
object
1 property
VoiceWebhook
object
5 properties
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Bird 12
Other APIs Bird publishes across the network.
Bird Customer Data API
Bird Phone Numbers API
Bird Identity Verification API
Bird Touchpoints API
Bird Accounts API
Bird FAQ API
Bird Intent API
Bird SMS Messaging API
Bird Channels API
Bird Contacts API
Bird Conversations API
Bird Legacy MessageBird API
#Webhook
Where this information came from
This is an independent, third-party profile of Bird Webhooks API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.