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.

Service	Supported events	Supported filters	Documentation
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).	Channel events Message events
Navigators	outboud (sent messages);	navigatorID messageStatus	Navigators events
Numbers	10dlc.brand; 10dlc.brandVetting; 10dlc.campaign; endpoint	No filters are supported for this service.	Numbers events
Conversations	conversation.created; conversation.updated; conversation.updated;	channelId	Conversation events

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.

UI Guide

You can create, edit webhooks subscription via UI as well access logs (logs are only for errors when we can't deliver webhooks to your endpoint; we do not log successful requests here). You can find the WebHooks dashboard in the developer suite ("D") under the preference menu

Logs can be inspected by accessing the view log option in each subscription menu

API Reference Guide

In the following sections the way to interact with our API described.

1. Create a webhook subscription
2. List available webhook events
3. List webhook subscriptions
4. Update a webhook subscription
5. Delete a webhook subscription
6. Verifying a webhook
7. Webhook subscription logs

   1. List all logs for a webhook subscription
   2. Get webhook log details by request ID