Create a webhook subscription

Error while loading OpenAPI operation — Invalid OpenAPI document

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