# Create a webhook subscription

## Create a webhook subscription

> To start receiving notifications via webhooks, the first step is to create a subscription. A webhook subscription specifies the destination URL for events and defines how they should be filtered. During setup, you can select which events to send to the specified URL.\
> You can create multiple webhook subscriptions to route different types of events to various URLs as needed.\
> Event filters are applied using AND operators, meaning that all specified criteria must be met for an event to be sent.\
> If you want to handle multiple interactionTypes, you’ll need to create separate webhook subscriptions for each.<br>

```json
{"openapi":"3.0.3","info":{"title":"Notifications","version":"1.0.0"},"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateWebhookSubscription":{"allOf":[{"type":"object","required":["service","event","url"],"additionalProperties":false,"properties":{"service":{"$ref":"#/components/schemas/WebhookService"},"event":{"$ref":"#/components/schemas/WebhookEvent"},"eventFilters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/WebhookEventFilter"},"description":"Filters to apply to the events that are sent to the webhook. This is a key-value list of filters that are specific to the service that the webhook is subscribed to.\nOne example would be a key of `channelId` and a value of a UUID (in string format) that represents a channel.\n"},"template":{"type":"string"},"url":{"$ref":"#/components/schemas/Url"},"signingKey":{"$ref":"#/components/schemas/SigningKey"}},"oneOf":[{"$ref":"#/components/schemas/EventFiltersChannels"},{"$ref":"#/components/schemas/EventFiltersNumbers"},{"$ref":"#/components/schemas/EventFiltersPayments"},{"$ref":"#/components/schemas/EventFiltersConversations"},{"$ref":"#/components/schemas/EventFiltersTemplates"}],"discriminator":{"propertyName":"service","mapping":{"channels":"#/components/schemas/EventFiltersChannels","numbers":"#/components/schemas/EventFiltersNumbers","payments":"#/components/schemas/EventFiltersPayments","conversations":"#/components/schemas/EventFiltersConversations","templates":"#/components/schemas/EventFiltersTemplates"}}}]},"WebhookService":{"type":"string","enum":["channels","numbers","payments","conversations","templates"],"description":"The service that the webhook is subscribed to. For example, to get events regarding channels, the service would be `channels`.\n"},"WebhookEvent":{"type":"string","description":"The event name identifies the webhook event, such as `sms.outbound` for notifications about SMS messages being sent.\n"},"WebhookEventFilter":{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string","enum":["channelId","platformId","channelStatus","interactionType","messageStatus","status","eventDestination","navigatorId"]},"value":{"type":"string"}},"description":"Filters used to narrow down events sent to the webhook. For example, if you want to receive events for a specific platform,\na valid filterKey would be `platformId` with a value of `sms`.\n"},"Url":{"type":"string","pattern":"^https://([a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}(/[^\\s]*)?$","description":"The URL of the webhook is used to send events to the webhook. The URL must be a valid URL that respects the established pattern and is accessible from the internet.\n"},"SigningKey":{"type":"string","description":"The signing key for the webhook and can be used to verify the authenticity of the webhook.\n"},"EventFiltersChannels":{"type":"object","title":"Channels service filters","properties":{"service":{"type":"string","enum":["channels"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"oneOf":[{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["channelId"]},"value":{"type":"string","format":"uuid"}}},{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["messageStatus","interactionType","channelStatus","platformId","status"]},"value":{"type":"string"}}}]}}}},"EventFiltersNumbers":{"type":"object","title":"Numbers service filters","properties":{"service":{"type":"string","enum":["numbers"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"additionalProperties":false,"description":"The numbers service does not have any specific filters for its events.\n","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"EventFiltersPayments":{"type":"object","title":"Numbers service filters","properties":{"service":{"type":"string","enum":["payments"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"EventFiltersConversations":{"type":"object","title":"Conversations service filters","properties":{"service":{"type":"string","enum":["conversations"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"oneOf":[{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["channelId"]},"value":{"type":"string","format":"uuid"}}}]}}}},"EventFiltersTemplates":{"type":"object","title":"Templates service filters","properties":{"service":{"type":"string","enum":["templates"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"oneOf":[{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["platformId"]},"value":{"type":"string"}}}]}}}},"WebhookSubscription":{"type":"object","required":["id","organizationId","workspaceId","service","event","url","status"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier for the webhook subscription. This identifier is used to reference the webhook subscription in other API calls.\n"},"organizationId":{"$ref":"#/components/schemas/WebhookOrganizationId"},"workspaceId":{"$ref":"#/components/schemas/WebhookWorkspaceId"},"service":{"$ref":"#/components/schemas/WebhookService"},"event":{"$ref":"#/components/schemas/WebhookEvent"},"eventFilters":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventFilter"}},"template":{"$ref":"#/components/schemas/Template"},"url":{"$ref":"#/components/schemas/Url"},"signingKey":{"$ref":"#/components/schemas/SigningKey"},"status":{"$ref":"#/components/schemas/WebhookSubscriptionStatus"},"statusReason":{"type":"string","description":"A human-readable explanation for the current status of the webhook subscription.\n"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookOrganizationId":{"type":"string","format":"uuid"},"WebhookWorkspaceId":{"type":"string","format":"uuid"},"Template":{"type":"string","description":"Used for our Exit APIs for Twilio and Sinch.\nMore information can be found [here](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/twilio-exit-api) for Twilio and [here](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/sinch-exit-api) for Sinch.\n"},"WebhookSubscriptionStatus":{"type":"string","enum":["active","inactive"]},"errorResponse":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/workspaces/{workspaceId}/webhook-subscriptions":{"post":{"summary":"Create a webhook subscription","description":"To start receiving notifications via webhooks, the first step is to create a subscription. A webhook subscription specifies the destination URL for events and defines how they should be filtered. During setup, you can select which events to send to the specified URL.\nYou can create multiple webhook subscriptions to route different types of events to various URLs as needed.\nEvent filters are applied using AND operators, meaning that all specified criteria must be met for an event to be sent.\nIf you want to handle multiple interactionTypes, you’ll need to create separate webhook subscriptions for each.\n","operationId":"createWebhookSubscription","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookSubscription"}}}},"responses":{"201":{"description":"The webhook subscription was created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"400":{"description":"Invalid HTTP request. The HTTP response should include details about the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}},"422":{"description":"The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}}}
```

To know more about how to use signingKeys, please refer to the section [Verifying a webhook](https://docs.bird.com/api/notifications-api/api-reference/webhook-subscriptions/verifying-a-webhook-subscription).

***

### Examples

Let's establish some of our data that will be used in the following examples:

* **Workspace ID**: a1405560-c8d3-4b1a-877d-3f449ad95352
* **AccessKey:** abcd

&#x20;**Creating a subscription for events of a specific channel**

In this example, we're sending event notifications for each sent message by the specified channel. To know more about valid events for each platform (e.g. SMS, E-mail), please refer [to this documentation](https://docs.bird.com/api/channels-api/message-status-and-interactions).&#x20;

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/webhook-subscriptions" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "service": "channels",
  "event": "sms.outbound",
  "url": "https://webhook.site/68be485e-5faa-4363-8033-2e3d236830db",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "3e3a68da-85a2-4b12-b114-b2c28117bf37"
    }
  ]
}'
```

{% endtab %}

{% tab title="Response (201 - Created)" %}

```json
{
  "id": "6eb139df-83c7-4541-b74a-e02f931023e7",
  "organizationId": "823fbfaf-f14e-4693-b55a-8ec1c17d649e",
  "workspaceId": "a1405560-c8d3-4b1a-877d-3f449ad95352",
  "service": "channels",
  "event": "sms.outbound",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "3e3a68da-85a2-4b12-b114-b2c28117bf37"
    }
  ],
  "template": "",
  "url": "https://webhook.site/68be485e-5faa-4363-8033-2e3d236830db",
  "status": "active",
  "createdAt": "2024-11-25T11:52:21.429367605Z",
  "updatedAt": "2024-11-25T11:52:21.429367776Z"
}
```

{% endtab %}
{% endtabs %}

**Creating a webhook subscription and filtering events based on interaction type**

This will send notification events to the specified webhook URL when an e-mail sent by the specified channel is opened by end-customers. To know more about all supported interactions, refer to [this documentation.](https://docs.bird.com/api/channels-api/message-status-and-interactions)

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/webhook-subscriptions" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "service": "channels",
  "event": "email.interaction",
  "url": "https://webhook.site/68be485e-5faa-4363-8033-2e3d236830db",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "3e3a68da-85a2-4b12-b114-b2c28117bf37"
     {
      "key": "interactionType",
      "value": "opened"
    }
  ],
}'
```

{% endtab %}

{% tab title="Response (201 - Created)" %}

```json
{
  "id": "0edf722b-93b4-4451-8a5d-4fafba5cdf8b",
  "organizationId": "ff1a5949-a704-48d2-99d9-b2cdfb7fef3e",
  "workspaceId": "b2d7a013-86df-4aa7-8245-8f3715c87ae2",
  "service": "channels",
  "event": "email.interaction",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "3e3a68da-85a2-4b12-b114-b2c28117bf37"
    },
    {
      "key": "interactionType",
      "value": "opened"
    }
  ],
  "template": "",
  "url": "https://webhook.site/68be485e-5faa-4363-8033-2e3d236830db",
  "status": "active",
  "createdAt": "2024-11-25T12:30:55.13273004Z",
  "updatedAt": "2024-11-25T12:30:55.132730139Z"
}
```

{% endtab %}
{% endtabs %}

**Creating a webhook subscription without filtering**

This will send notification events to the specified webhook URL for all email interactions. To know more about all supported interactions, refer to [this documentation.](https://docs.bird.com/api/channels-api/message-status-and-interactions)

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/webhook-subscriptions" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "service": "channels",
  "event": "email.interaction",
  "url": "https://webhook.site/68be485e-5faa-4363-8033-2e3d236830db",
}'
```

{% endtab %}

{% tab title="Response (201 - Created)" %}

```json
{
  "id": "94a2f6c8-47ae-4819-befb-6751c019713b",
  "organizationId": "ff1a5949-a704-48d2-99d9-b2cdfb7fef3e",
  "workspaceId": "b2d7a013-86df-4aa7-8245-8f3715c87ae2",
  "service": "channels",
  "event": "email.interaction",
  "eventFilters": [],
  "template": "",
  "url": "https://webhook.site/68be485e-5faa-4363-8033-2e3d236830db",
  "status": "active",
  "createdAt": "2024-11-25T13:53:46.449354369Z",
  "updatedAt": "2024-11-25T13:53:46.449354517Z"
}
```

{% endtab %}
{% endtabs %}