Webhook subscriptions
Webhook subscriptions enable your application to receive real-time notifications about events such as outbound and inbound messages, including interactions. Each webhook can be configured with a unique URL and a list of events to subscribe to for notifications. You can create multiple webhooks, each with its own URL, to monitor one or more events. Bird also allows customers to customize their webhook subscriptions by filtering specific events based on channels, statuses, or interaction types.
General definitions
Retries: If Bird does not receive a 2xx response from your webhook endpoint, it will automatically retry the failed notification. The retries will occur at increasing intervals over a period of 8 hours. For more information, check the Retries section below.
Maximum Matching Subscriptions: You can create up to five subscriptions for the same filter combination. For example, if you want to send events from a specific channel to five different URLs, you can achieve this by creating five webhook subscriptions with the same filters but different URLs.
Multiple Condition Filtering: You can apply multiple filters to capture specific events. All filtering conditions must be met for an event to be collected. For instance, if you set filters for a specific channel ID and an interaction type, only events matching both the specified interaction type and channel ID will be collected.
Valid filters: you can be notified about dozen events across our services. You can know more about them in the following table. Please refer to the complete documentation to discover more about valid values for filters. The API documentation also references it with examples about how to interact with them.
Channels
inbound (received messages);
outbound (sent messages);
interaction (e.g. if an end-customer opened an email).
channel created;
channel updated;
channelId;
messageStatus;
interactionType
platformId,
channelStatus
status (for voice, to filter events by call status).
Numbers
10dlc.brand;
10dlc.brandVetting;
10dlc.campaign;
endpoint
No filters are supported for this service.
Conversations
conversation.created;
conversation.updated;
conversation.updated;
channelId
Retries
When Bird fails to deliver an event to your webhook, request are retried if any of the following conditions are met:
The webhook didn't respond after 30 seconds;
The webhook responded with an error status (4XX or 5XX);
The DNS lookup of the webhook's domain failed;
A network error occurred.
When facing scenarios like timeouts, from your perspective it may look like the same event was duplicated due to retries, so make sure your webhook responds quickly by avoiding long-running operations. This can be achieved with a message queue or similar asynchronous communication mechanism that allows events to be processed at a later time.
You can troubleshoot webhook issues by checking out webhook logs in the UI.
API Reference Guide
In the following sections the way to interact with our API described.
Last updated