# 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](#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.

<table><thead><tr><th width="131.91796875">Service</th><th width="226.24609375">Supported events</th><th width="233">Supported filters</th><th>Documentation</th></tr></thead><tbody><tr><td>Channels</td><td><ul><li>inbound (received messages);</li><li><em>outbound (sent messages);</em></li><li><em>interaction (e.g. if an end-customer opened an email).</em></li><li><em>channel created;</em></li><li><em>channel updated;</em></li></ul></td><td><ul><li><em>channelId;</em></li><li><em>messageStatus;</em></li><li><em>interactionType</em></li><li><em>platformId,</em></li><li><em>channelStatus</em></li><li><em>status (for voice, to filter events by call status).</em></li></ul></td><td><ul><li><a href="../../channels-api/api-reference/events">Channel events</a></li><li><a href="../../channels-api/message-status-and-interactions">Message events </a></li></ul></td></tr><tr><td>Navigators</td><td><ul><li><em>outbound (sent messages);</em></li></ul></td><td><ul><li><em>navigatorID</em></li><li><em>messageStatus</em></li></ul></td><td><ul><li><a href="../../../channels-api/api-reference/navigators#check-navigators-messages-status-reports">Navigators events</a></li></ul></td></tr><tr><td>Numbers</td><td><ul><li><em>endpoint;</em></li><li><em>10dlc.brand;</em></li><li><em>10dlc.brandVetting;</em></li><li><em>10dlc.campaign;</em></li><li><em>tfn.verification;</em></li></ul></td><td>No filters are supported for this service.</td><td><ul><li><a href="../../numbers-api/api-reference/events">Numbers events</a></li></ul></td></tr><tr><td>Conversations</td><td><ul><li><em>conversation.created;</em></li><li><em>conversation.updated;</em></li><li><em>conversation.updated;</em></li></ul></td><td><ul><li><em>channelId</em></li></ul></td><td><ul><li><a href="../../conversations-api/api-reference/events">Conversation events</a></li></ul></td></tr></tbody></table>

{% hint style="info" %}
use the `channels interaction` subscription to keep track of suppression and unsubscription, such as `keyword_unsubscribe` , `keyword_consent` and `link_unsubscribe.` You will need a subscription for each platform (email, sms , WhatsApp etc )
{% endhint %}

## 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&#x20;

<figure><img src="https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FyfNDaHaDsd5paqSv4JoN%2Fimage.png?alt=media&#x26;token=2b5c6482-82fd-421c-af6f-f0a8a0b35274" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FIr8qwD6Dc1kkbKQDjyLi%2Fimage.png?alt=media&#x26;token=a99dd0b5-dcea-43d1-95d3-1c5e2c4d4d22" alt=""><figcaption></figcaption></figure>

## API Reference Guide

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

1. [Create a webhook subscription](https://docs.bird.com/api/notifications-api/api-reference/webhook-subscriptions/create-a-webhook-subscription)
2. [List available webhook events](https://docs.bird.com/api/notifications-api/api-reference/webhook-subscriptions/list-available-webhook-events)
3. [List webhook subscriptions](https://docs.bird.com/api/notifications-api/api-reference/webhook-subscriptions/list-webhook-subscriptions)
4. [Update a webhook subscription](https://docs.bird.com/api/notifications-api/api-reference/webhook-subscriptions/update-a-webhook-subscription)
5. [Delete a webhook subscription](https://docs.bird.com/api/notifications-api/api-reference/webhook-subscriptions/delete-a-webhook-subscription)
6. [Verifying a webhook](https://docs.bird.com/api/notifications-api/api-reference/webhook-subscriptions/verifying-a-webhook-subscription)
7. [Webhook subscription logs](https://docs.bird.com/api/notifications-api/api-reference/webhook-subscriptions/webhook-subscription-logs)
   1. [List all logs for a webhook subscription](https://docs.bird.com/api/notifications-api/api-reference/webhook-subscription-logs#organizations-organizationid-workspaces-workspaceid-webhook-subscriptions-webhooksubscriptionid-logs)
   2. [Get webhook log details by request ID](https://docs.bird.com/api/notifications-api/api-reference/webhook-subscription-logs#organizations-organizationid-workspaces-workspaceid-webhook-subscriptions-webhooksubscriptionid-logs-1)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/api/notifications-api/api-reference/webhook-subscriptions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.