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.

POSThttps://api.bird.com/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions

Path parameters

workspaceId*Workspace ID

The ID for the workspace.

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

organizationId*Organization ID

The ID for the organization.

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

Body

application/json

service*Notifications_WebhookService (enum)

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

channelsnumberspaymentsconversations

event*Notifications_WebhookEvent (string)

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

Example: "sms.outbound"

eventFiltersnullable array of Notifications_WebhookEventFilter (object)

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.

templatestring

url*Notifications_Url (string)

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]*)?$

signingKeyNotifications_SigningKey (string)

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

Example: "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk="

Response

201400422

The webhook subscription was created successfully.

Body

application/json

id*string (uuid)

The unique identifier for the webhook subscription. This identifier is used to reference the webhook subscription in other API calls.

organizationId*Notifications_WebhookOrganizationId (string (uuid))

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

workspaceId*Notifications_WebhookWorkspaceId (string (uuid))

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

service*Notifications_WebhookService (enum)

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

channelsnumberspaymentsconversations

event*Notifications_WebhookEvent (string)

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

Example: "sms.outbound"

eventFiltersarray of Notifications_WebhookEventFilter (object)

templateNotifications_Template (string)

Used for our Exit APIs for Twilio and Sinch. More information can be found here for Twilio and here for Sinch.

Example: "twilio"

url*Notifications_Url (string)

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]*)?$

signingKeyNotifications_SigningKey (string)

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

Example: "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk="

status*Notifications_WebhookSubscriptionStatus (enum)

activeinactive

createdAtstring (date-time)

updatedAtstring (date-time)

Request

JavaScriptCurlPython

const response = await fetch('https://api.bird.com/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "service": "channels",
      "event": "sms.outbound",
      "url": "https://example.com/webhook"
    }),
});
const data = await response.json();

Response

201400422

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

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