Subscribe to channel webhooks

Finally to receive webhooks for your newly created channel you should subscribe to channels webhooks as described in detail here. To subscribe to all events (message status, interactions, incoming messages) you can make the following requests using the channel id you just received.

Set up a webhook subscription

post

/organizations/{organization_id}/workspaces/{workspace_id}/webhook-subscription

Path parameters

organization_idstringrequired

The ID of the organization

workspace_idstringrequired

The ID of the workspace

Body

servicestring

eventstring

templatestring

urlstring

signingKeystring

eventFiltersobject[]

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/organizations/{organization_id}/workspaces/{workspace_id}/webhook-subscription' \
  --header 'Content-Type: application/json' \
  --data '{"eventFilters":[{}]}'

200

400

200

No body

Successful response

Incoming messages

Replace {{webhook_url}} with an endpoint you will recieve webhooks and {{signing_key}} is a secret you can use to verify the webhook. Filter by {{channel_id}} to just get webhooks for this channel

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/numbers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
  "service": "channels",
  "event": "whatsapp.inbound",
  "url": "{{webhook_url}}",
  "signingKey": "{{signing_key}}",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "{{channelid}}"
    }
  ]
}'

Message status update

Replace {{webhook_url}} with an endpoint you will recieve webhooks and {{signing_key}} is a secret you can use to verify the webhook. Filter by {{channel_id}} to just get webhooks for this channel

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/numbers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
  "service": "channels",
  "event": "whatsapp.outbound",
  "url": "{{webhook_url}}",
  "signingKey": "{{signing_key}}",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "{{channel_id}}"
    },
    {
      "key": "messageStatus",
      "value": "sending_failed”
    },
    {
      "key": "messageStatus",
      "value": "sent"
    },
    {
      "key": "messageStatus",
      "value": "delivery_failed"
    },
    {
      "key": "messageStatus",
      "value": "delivered"
    }
  ]
}
'

Message interactions

Replace {{webhook_url}} with an endpoint you will recieve webhooks and {{signing_key}} is a secret you can use to verify the webhook. Filter by {{channel_id}} to just get webhooks for this channel

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/numbers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
  "service": "channels",
  "event": "whatsapp.interaction",
  "url": "{{webhook_url}}",
  "signingKey": "{{signing_key}}",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "{{channel_id}}"
    }
  ]
}
'

Where next

Before fully completing the integration be sure to request advanced permissions access and complete access verification.

Now you have completed the basics of onboarding you can begin sending and receiving messages to your channel. To get started:

1. Create message templates

2. Manage channels

   1. Check if the customer service window is open

3. Send messages

4. List messages

5. List message interactions