anchorBefore you begin

This page covers /v1/webhooks. Contact Center event subscriptions use a different registration guide. A Contact Center application still uses this guide when subscribing to platform Service App authorization events.

Choose a resource and event from the event reference. Obtain an OAuth token with the required resource access and ownership permissions. Expose a publicly reachable HTTPS receiver and generate a unique signing secret for each registration. Configure the receiver before triggering test events.

For message notifications, the token needs spark:messages_read. Membership notifications require spark:memberships_read. See Scopes for application scope selection. Other resources and organization-level registrations have their own requirements below and in the resource API reference.

For Calling resources, check the interest registration prerequisites. Some resource or actor categories require an interest registration in addition to a webhook; interests expire and must be refreshed. These registrations affect applicable webhooks across the organization.

anchorOrg/Admin/Compliance Officer level webhooks

Admins/Compliance Officers often want to have an org wide view of meeting events. Admins registered in Control Hub with the Full admin role have the capability to register webhooks for their org by setting an additional field ownedBy with the value set to org. Compliance officers can also register webhooks for their org by setting the value of ownedBy field with the value set to org. Both can filter to specific sites in the org or specific hosts by using the corresponding filter parameters described below. To register for meeting events at Org level, the Org admin should also be a Webex site admin managing the relevant Webex sites or a Compliance officer for the organization. Integrations acting on-behalf of an admin need to have the Admin level scope to register org wide webhooks.

anchorChoosing applications vs serviceApp webhooks

Use the applications webhook resource when you need org-wide notifications that a Bot, Integration, or Service App in your organization was created, updated, or deleted. Use the serviceApp resource when you need notifications that a Service App was authorized or deauthorized by an administrator. Use spark:applications_webhook_write on the token that creates the webhook. The API also accepts application:webhooks_write or spark:all. Select the webhook scope on the Integration or Service App that calls Create Webhook.

anchorUser Level Scopes for Meeting Related Webhooks

The following scopes are required to create, get, list, update or delete webhooks at user level for meeting related resources:

anchorOrganization/Admin/Compliance Officer Level Scopes for Meeting Related Webhooks

The following scopes are required to create, get, list, update or delete webhooks at organization level for meeting related resources:

anchorFiltering Webhooks

In order to narrow down the data that you receive from webhooks, you can add filters to your webhooks. To do this, you can create a webhook for a resource that applies to an event, and then add a filter or a combination of filters to send you only notification content that is based on the added filter restrictions. For example, you can register a webhook for a membership resource and then add filters so that the webhook only applies to a specific room, by using its roomId filter.

You can also use more than one filter in a webhook. To use multiple filters, combine them with the “&” symbol. For example, to create a webhook that only sends notifications when a specific person performs an action in a specific room, such as sending a message or creating a membership, combine the personEmail and roomId filters: personEmail=person@example.com&roomId=abc123.

See the event reference for the filters supported by each resource.

Alternatively, Webhooks also support what is commonly known as a “firehose” or “wildcard” webhook, which allows your app to subscribe to several commonly-used resources and/or events with a single webhook. For more information, see The Firehose Webhook.

anchorThe Firehose Webhook

The Webhooks resource supports what is commonly known as a “firehose” or “wildcard” webhook, which allows your app to subscribe to all events from several commonly-used resources with a single webhook. There are two types of firehoses. One is a “single resource firehose” and the other is an “all resource” firehose.

The event expansion depends on whether you select one resource or all resources. An all-resource registration covers memberships, messages, and rooms.

Single Resource Firehose

A single-resource firehose uses event: "all" to select the resource’s supported wildcard event set. For example, to subscribe to all events for the messages resource, your app can create a webhook as shown below:

{
  "name": "Messages Firehose",
  "targetUrl": "https://example.com/message-events",
  "resource": "messages",
  "event": "all"
}

For meetings, event: "all" includes created, updated, deleted, started, and ended. For meetingParticipants, it includes joined and left. The standard wildcard set for other supported resources is created, updated, and deleted; do not assume all includes every specialized event in the reference. Resource permissions and feature availability still apply.

All Resource Firehose

An all resource firehose webhook will send a notification for any event for all supported resource types. The following resources will be included in the “all resource” firehose: memberships, messages, and rooms.

For example, to subscribe to all events that occur on all supported resources, create a webhook with the resource set to all and the event set to all as shown below:

{
  "name": "Awesome Bot Webhook Firehose",
  "targetUrl": "https://example.com/spark-events",
  "resource": "all",
  "event": "all"
}

anchorCreating a Webhook

To begin receiving platform events, you first need to register a webhook with Webex. To create a webhook, make an HTTP POST to /webhooks with some basic information as shown in the example below:

{
  "name": "New message in 'Project Unicorn' room",
  "targetUrl": "https://example.com/spark-hook",
  "resource": "messages",
  "event": "created",
  "filter": "roomId=Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0"
}

Request Parameters

A valid OAuth token is required to create a webhook. An existing webhook can continue sending notifications after the token used to register it expires, provided your endpoint acknowledges deliveries successfully. Payload contents vary by resource; for example, applications updates include an application lifecycle snapshot. Treat every delivery as sensitive: use HTTPS for the target URL, set a unique secret, and verify the signature over the raw request body before logging or processing the payload. See Authenticating Requests for details.

Applications webhook examples

Register a separate webhook for each event you want to receive (created, updated, or deleted). Omit the filter field—filters are not supported for applications webhooks. Generate a different high-entropy secret for each registration, store it in a secret manager, and substitute that value for the illustrative secret strings below before making the API request. Verify each delivery signature before processing it.

Created — notify when an application is added to the organization:

{
  "name": "Org applications created",
  "targetUrl": "https://example.com/webhooks/applications-created",
  "resource": "applications",
  "event": "created",
  "secret": "<unique-secret-from-secret-manager>",
  "ownedBy": "org"
}

Updated — notify when an application is modified (payload includes an application lifecycle snapshot):

{
  "name": "Org applications updated",
  "targetUrl": "https://example.com/webhooks/applications-updated",
  "resource": "applications",
  "event": "updated",
  "secret": "<unique-secret-from-secret-manager>",
  "ownedBy": "org"
}

Deleted — notify when an application is removed:

{
  "name": "Org applications deleted",
  "targetUrl": "https://example.com/webhooks/applications-deleted",
  "resource": "applications",
  "event": "deleted",
  "secret": "<unique-secret-from-secret-manager>",
  "ownedBy": "org"
}

Verify applications deliveries using the receiver guide. It owns signature verification, acknowledgement, and retry handling.

For updated events, data contains an application lifecycle snapshot. Compare its documented fields with your stored state to identify changes. Do not assume the snapshot matches the complete response of an application details API.

Organizations with federated identity may experience additional webhook delivery latency.

Troubleshooting applications webhooks

anchorComplete registration request

Send the following request with your own access token, test space ID, HTTPS destination, and unique signing secret. The placeholders are illustrative; do not send them literally.

POST https://webexapis.com/v1/webhooks
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "name": "Test message created",
  "targetUrl": "https://example.com/webhooks/messages",
  "resource": "messages",
  "event": "created",
  "filter": "roomId=<test-room-id>",
  "secret": "<unique-secret-from-secret-manager>"
}

anchorReceive your first event

1. Select a test Webex space your token can access and obtain its room ID with List Rooms.
2. Use Create a Webhook with resource: messages, event: created, filter: roomId=<test-room-id>, your HTTPS targetUrl, and a unique secret. Store the returned registration ID and its secret together. Add the secret to the message example above before submitting it.
3. Post a message in that space. Expect a delivery with resource: messages, event: created, and a data.id identifying the message.
4. Verify the delivery signature over its original bytes. Accept the event durably before acknowledging it, then fetch message content with your application token if needed. See Receive and verify events.
5. Inspect the registration with Get Webhook Details. The envelope id should match this registration, not the individual message.
6. Delete only this test registration with Delete a Webhook.

anchorManage registration lifecycle

Registration limits depend on ownership, resources, and filters. Wildcard registrations can count as several resource/event registrations. Organization-owned duplicate checks also distinguish the application, resource, event, and filter; do not interpret the limit as one webhook for an entire organization. Consult the API reference and confirm the applicable limit with developer support before designing high-volume provisioning.