Create a webhook subscription

post

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.

Authorizations

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

The ID for the workspace.

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

Body

servicestring · enumRequired

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

Possible values:

eventstringRequired

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

Example: sms.outbound

templatestringOptional

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/webhookPattern: ^https://([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(/[^\s]*)?$

signingKeystringOptional

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

Example: KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk=

Responses

201

The webhook subscription was created successfully.

application/json

idstring · uuidRequired

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

organizationIdstring · uuidRequiredExample: cb28a94e-8557-4394-80ea-5bbd2170d434

workspaceIdstring · uuidRequiredExample: b4e02c85-c6d2-4b15-8885-e09671799c61

servicestring · enumRequired

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

Possible values:

eventstringRequired

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

Example: sms.outbound

templatestringOptional

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

Example: twilio

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/webhookPattern: ^https://([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(/[^\s]*)?$

signingKeystringOptional

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

Example: KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk=

statusstring · enumRequiredPossible values:

statusReasonstringOptional

A human-readable explanation for the current status of the webhook subscription.

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

400

Invalid HTTP request. The HTTP response should include details about the error.

application/json

422

The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.

application/json

post

/workspaces/{workspaceId}/webhook-subscriptions

POST /workspaces/{workspaceId}/webhook-subscriptions HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 243

{
  "service": "channels",
  "event": "sms.outbound",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "58c44c1d-a6a0-4cb6-9f78-05308de87451"
    }
  ],
  "template": "text",
  "url": "https://example.com/webhook",
  "signingKey": "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk="
}

{
  "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",
  "statusReason": "text",
  "createdAt": "2026-03-26T20:00:36.593Z",
  "updatedAt": "2026-03-26T20:00:36.593Z"
}

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
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.

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

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

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"
    }
  ],
}'

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

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

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

Last updated 1 month ago

Was this helpful?

hashtagCreate a webhook subscription

hashtagExamples

Create a webhook subscription

Examples