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.

post

/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions

Authorizations

MessageBird_userMessageBird_accessKey

Path parameters

workspaceIdWorkspace IDrequired

The ID for the workspace.

Example: b4e02c85-c6d2-4b15-8885-e09671799c61

organizationIdOrganization IDrequired

The ID for the organization.

Example: cb28a94e-8557-4394-80ea-5bbd2170d434

Body

servicestring · enumrequired

The service that the webhook is subscribed to. For example, to get events regarding channels, the service would be channels.

Options: channels, numbers, payments, conversations

eventstringrequired

The event name identifies the webhook event, such as sms.outbound for notifications about SMS messages being sent.

Example: sms.outbound

templatestring

urlstringrequired

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.

Example: https://example.com/webhook

Pattern: ^https://([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(/[^\s]*)?$

signingKeystring

The signing key for the webhook and can be used to verify the authenticity of the webhook.

Example: KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk=

eventFiltersobject[] | nullable

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. One example would be a key of channelId and a value of a UUID (in string format) that represents a channel.

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.bird.com/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"service":"channels","event":"sms.outbound","url":"https://example.com/webhook","signingKey":"KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk=","eventFilters":[]}'

201

400

422

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "cb28a94e-8557-4394-80ea-5bbd2170d434",
  "workspaceId": "b4e02c85-c6d2-4b15-8885-e09671799c61",
  "service": "channels",
  "event": "sms.outbound",
  "template": "twilio",
  "url": "https://example.com/webhook",
  "signingKey": "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk=",
  "status": "active",
  "createdAt": "2025-02-21T18:02:27.121Z",
  "updatedAt": "2025-02-21T18:02:27.121Z",
  "eventFilters": [
    {
      "value": "clicked",
      "key": "channelId"
    }
  ]
}

The webhook subscription was created successfully.

To know more about how to use signingKeys, please refer to the section Verifying a webhook.

Examples

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

• Workspace ID: a1405560-c8d3-4b1a-877d-3f449ad95352

• Organization ID: 823fbfaf-f14e-4693-b55a-8ec1c17d649e

• AccessKey: abcd

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.

Request

curl -X POST "https://api.bird.com/organizations/823fbfaf-f14e-4693-b55a-8ec1c17d649e/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"
    }
  ]
}'

Response (201 - Created)

{
  "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"
}

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.

Request

curl -X POST "https://api.bird.com/organizations/823fbfaf-f14e-4693-b55a-8ec1c17d649e/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"
    }
  ],
}'

Response (201 - Created)

{
  "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"
}

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.

Request

curl -X POST "https://api.bird.com/organizations/823fbfaf-f14e-4693-b55a-8ec1c17d649e/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",
}'

Response (201 - Created)

{
  "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"
}