DokumentationEngagement Platform API
Sign inGet started
Guides
API

Update a webhook subscription

PATCH
/workspaces/{workspaceId}/webhook-subscriptions/{webhookSubscriptionId}
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.
Anfrage-Payload
template
string
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.
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. Included fields are updated. Omitted fields are preserved. Setting this field to null disables OAuth.
Untergeordnete Parameter anzeigen
oauth2.tokenUrl
string
The OAuth 2.0 token endpoint where access tokens are requested.
oauth2.clientId
string
The OAuth 2.0 client identifier.
oauth2.clientSecret
string
The OAuth 2.0 client secret.
oauth2.scopes
array of string
OAuth 2.0 scopes to request.
status
string
Possible values: active, inactive
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.
Untergeordnete Parameter anzeigen
eventFilters.key
string
erforderlich
Possible values: channelId, platformId, channelStatus, interactionType, messageStatus, status, eventDestination, navigatorId
eventFilters.value
string
erforderlich
Antwort-Payload
id
string
erforderlich
The unique identifier for the webhook subscription. This identifier is used to reference the webhook subscription in other API calls.
organizationId
string
erforderlich
workspaceId
string
erforderlich
service
string
erforderlich
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
erforderlich
The event name identifies the webhook event, such as sms.outbound for notifications about SMS messages being sent.
eventFilters
array of object
Untergeordnete Attribute anzeigen
eventFilters.key
string
erforderlich
Possible values: channelId, platformId, channelStatus, interactionType, messageStatus, status, eventDestination, navigatorId
eventFilters.value
string
erforderlich
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
erforderlich
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.
Untergeordnete Attribute anzeigen
oauth2.tokenUrl
string
erforderlich
The OAuth 2.0 token endpoint where access tokens are requested.
oauth2.clientId
string
erforderlich
The OAuth 2.0 client identifier.
oauth2.scopes
array of string
OAuth 2.0 scopes to request.
status
string
erforderlich
Possible values: active, inactive
statusReason
string
A human-readable explanation for the current status of the webhook subscription.
createdAt
string
updatedAt
string
Codebeispiel
curl -X PATCH 'https://api.bird.com/workspaces/{workspaceId}/webhook-subscriptions/{webhookSubscriptionId}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Examples

Let's establish some of our data that will be used in the following examples:
  • Workspace ID: a1405560-c8d3-4b1a-877d-3f449ad95352
  • 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.
Codebeispiel
curl -X PATCH "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/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.
Codebeispiel
curl -X PATCH "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/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"
}'