Update a webhook subscription

Update a webhook subscription

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.

PATCHhttps://api.bird.com/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions/{webhookSubscriptionId}

Path parameters

workspaceId*Workspace ID

The ID for the workspace.

Example: "b4e02c85-c6d2-4b15-8885-e09671799c61"

organizationId*Organization ID

The ID for the organization.

Example: "cb28a94e-8557-4394-80ea-5bbd2170d434"

webhookSubscriptionId*WebhookSubscriptionID

The ID for the webhook subscription.

Example: "852883af-5f68-4204-b611-7ee8db9600f4"

Body

application/json

templatestring

urlNotifications_Url (string)

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/webhook"

Pattern: ^https://([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(/[^\s]*)?$

signingKeyNotifications_SigningKey (string)

The signing key for the webhook and can be used to verify the authenticity of the webhook.

Example: "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk="

statusNotifications_WebhookSubscriptionStatus (enum)

activeinactive

Response

200404422

The webhook subscription was updated successfully.

Body

application/json

id*string (uuid)

The unique identifier for the webhook subscription. This identifier is used to reference the webhook subscription in other API calls.

organizationId*Notifications_WebhookOrganizationId (string (uuid))

Example: "cb28a94e-8557-4394-80ea-5bbd2170d434"

workspaceId*Notifications_WebhookWorkspaceId (string (uuid))

Example: "b4e02c85-c6d2-4b15-8885-e09671799c61"

service*Notifications_WebhookService (enum)

The service that the webhook is subscribed to. For example, to get events regarding channels, the service would be channels.

channelsnumberspaymentsconversations

event*Notifications_WebhookEvent (string)

The event name identifies the webhook event, such as sms.outbound for notifications about SMS messages being sent.

Example: "sms.outbound"

eventFiltersarray of Notifications_WebhookEventFilter (object)

templateNotifications_Template (string)

Used for our Exit APIs for Twilio and Sinch. More information can be found here for Twilio and here for Sinch.

Example: "twilio"

url*Notifications_Url (string)

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/webhook"

Pattern: ^https://([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(/[^\s]*)?$

signingKeyNotifications_SigningKey (string)

The signing key for the webhook and can be used to verify the authenticity of the webhook.

Example: "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk="

status*Notifications_WebhookSubscriptionStatus (enum)

activeinactive

createdAtstring (date-time)

updatedAtstring (date-time)

Request

JavaScriptCurlPython

const response = await fetch('https://api.bird.com/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions/{webhookSubscriptionId}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200404422

{
  "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": "2024-12-21T16:22:41.559Z",
  "updatedAt": "2024-12-21T16:22:41.559Z"
}

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)

{
  "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.example/68be485e-5faa-4363-8033-2e3d236830db",
  "status": "inactive",
  "createdAt": "2024-11-25T13:53:46.449354369Z",
  "updatedAt": "2024-11-25T14:12:32.005494986Z"
}

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)

{
  "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.another-example-url/68be485e-5faa-4363-8033-2e3d236830db",
  "status": "inactive",
  "createdAt": "2024-11-25T13:53:46.449354369Z",
  "updatedAt": "2024-11-25T14:12:32.005494986Z"
}