DocumentatieEngagement Platform API
Sign inGet started
Guides
API

Create a webhook subscription

POST
/workspaces/{workspaceId}/webhook-subscriptions
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.
Verzoek-payload
service
string
verplicht
The service that the webhook is subscribed to. For example, to get events regarding channels, the service would be channels.
Possible values: channels, numbers, payments, conversations, templates
event
string
verplicht
The event name identifies the webhook event, such as sms.outbound for notifications about SMS messages being sent.
eventFilters
array of 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.
Onderliggende parameters tonen
eventFilters.key
string
verplicht
Possible values: channelId, platformId, channelStatus, interactionType, messageStatus, status, eventDestination, navigatorId
eventFilters.value
string
verplicht
template
string
url
string
verplicht
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.
signingKey
string
The signing key for the webhook and can be used to verify the authenticity of the webhook.
oauth2
object
OAuth 2.0 client credentials configuration.
Onderliggende parameters tonen
oauth2.tokenUrl
string
verplicht
The OAuth 2.0 token endpoint where access tokens are requested.
oauth2.clientId
string
verplicht
The OAuth 2.0 client identifier.
oauth2.clientSecret
string
verplicht
The OAuth 2.0 client secret.
oauth2.scopes
array of string
OAuth 2.0 scopes to request.
Antwoord-payload
id
string
verplicht
The unique identifier for the webhook subscription. This identifier is used to reference the webhook subscription in other API calls.
organizationId
string
verplicht
workspaceId
string
verplicht
service
string
verplicht
The service that the webhook is subscribed to. For example, to get events regarding channels, the service would be channels.
Possible values: channels, numbers, payments, conversations, templates
event
string
verplicht
The event name identifies the webhook event, such as sms.outbound for notifications about SMS messages being sent.
eventFilters
array of object
Onderliggende attributen tonen
eventFilters.key
string
verplicht
Possible values: channelId, platformId, channelStatus, interactionType, messageStatus, status, eventDestination, navigatorId
eventFilters.value
string
verplicht
template
string
Used for our Exit APIs for Twilio and Sinch. More information can be found here for Twilio and here for Sinch.
url
string
verplicht
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.
signingKey
string
The signing key for the webhook and can be used to verify the authenticity of the webhook.
oauth2
object
OAuth 2.0 client credentials configuration.
Onderliggende attributen tonen
oauth2.tokenUrl
string
verplicht
The OAuth 2.0 token endpoint where access tokens are requested.
oauth2.clientId
string
verplicht
The OAuth 2.0 client identifier.
oauth2.scopes
array of string
OAuth 2.0 scopes to request.
status
string
verplicht
Possible values: active, inactive
statusReason
string
A human-readable explanation for the current status of the webhook subscription.
createdAt
string
updatedAt
string
Codevoorbeeld
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/webhook-subscriptions' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
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.
Codevoorbeeld
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"
    }
  ]
}'
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.
Codevoorbeeld
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"
    }
  ],
}'
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.
Codevoorbeeld
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",
}'