No-code docs

Update a webhook subscription

Update a webhook subscription

patch

Update a webhook subscription. This endpoint allows you to update the URL, event filters of a webhook subscription and other fields like the signingKey used to authenticate the request. You can also make the subscription inactive by setting the status to inactive.

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
organizationIdstring · uuidRequired

The ID for the organization.

Example: cb28a94e-8557-4394-80ea-5bbd2170d434
webhookSubscriptionIdstring · uuidRequired

The ID for the webhook subscription.

Example: 852883af-5f68-4204-b611-7ee8db9600f4
Body
templatestringOptional
urlstringOptional

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 · enumOptionalPossible values:
Responses
patch
/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions/{webhookSubscriptionId}
PATCH /organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions/{webhookSubscriptionId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 188

{
  "template": "text",
  "url": "https://example.com/webhook",
  "signingKey": "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk=",
  "status": "active",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "clicked"
    }
  ]
}
{
  "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": "2025-11-18T19:11:26.364Z",
  "updatedAt": "2025-11-18T19:11:26.364Z"
}

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

  • Webhook subscription to be updated ID: 0edf722b-93b4-4451-8a5d-4fafba5cdf8b

  • AccessKey: abcd

Deactivating a webhook subscription

If you want to quickly stop receiving event notifications, you can update the webhook subscription status to inactive. The following request exemplify how to proceed.

curl -X PATCH "https://api.bird.com/organizations/823fbfaf-f14e-4693-b55a-8ec1c17d649e/workspaces/{{workspaceId}}/webhook-subscriptions/0edf722b-93b4-4451-8a5d-4fafba5cdf8b" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "status": "inactive"
}'

Updating a webhook subscription URL

If you want to change the destination which the event notifications should go, you can update the URL. The following request exemplify how to proceed. 

curl -X PATCH "https://api.bird.com/organizations/823fbfaf-f14e-4693-b55a-8ec1c17d649e/workspaces/{{workspaceId}}/webhook-subscriptions/0edf722b-93b4-4451-8a5d-4fafba5cdf8b" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "url": "https://webhook.another-example-url/68be485e-5faa-4363-8033-2e3d236830db"
}'

Last updated

Was this helpful?