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

accessKey

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

application/json

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

200

The webhook subscription was updated successfully.

application/json

404

The webhook subscription was not found.

application/json

422

The request is invalid. The response should include details about the what is wrong with the request.

application/json

patch

/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions/{webhookSubscriptionId}

HTTPcURLJavaScriptPython

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",
  "statusReason": "text",
  "createdAt": "2026-01-27T16:46:13.305Z",
  "updatedAt": "2026-01-27T16:46:13.305Z"
}

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.

Request

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

Response (200 OK)

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.

Request

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

Response (200 OK)