APIs
Getting StartedREST API BasicsComplianceWebhooksWebex APIs
Admin
Calling
Contact Center
Devices
imiconnect
Meetings
Messaging
Webex Assistant Skills
Full API Reference
API Changelog

Webhooks

Use webhooks to notify your apps when specific activities occur in Webex.

anchorOverview
anchor

A webhook is an HTTP callback, or an HTTP POST, to a specified URL that notifies your app when a particular activity or “event” has occurred in one of your resources on the Webex platform. The benefit of using webhooks is that they allow your application to receive real-time data from Webex, so you can keep up with the state of your resources (i.e. rooms, messages, memberships, etc.).

For instance, let’s say you want to be notified when someone posts a message in a room that you’re interested in. You can create a webhook to have Webex notify you whenever new messages are posted into that room. So, instead of your app having to make repeated calls to the API to determine if a new message has been posted into the room, the webhook will automatically notify you of their occurrence.

Webhooks work well for your integrations and bots. For example, let’s say that you are creating a weather bot for Webex where users can ask your bot for the weather forecast in any city. You would want to use webhooks to let your app know when someone has sent a new weather request to your app. Your app can then take action, such as looking up the weather forecast for the requested city, and sending it back to the user.

You can create, or register, a webhook, via the Webex Webhooks API, to subscribe to the events in Webex that you would like to receive notifications for.

For information about Incoming Webhooks, where you can send information to Webex from outside services, see the Incoming Webhooks Integration by Cisco Systems in the Webex App Hub.

To learn more about webhooks and how to create them, keep reading. For a step-by-step tutorial that shows you how to create a webhook, see Experiment with Webex Webhooks Cisco DevNet Learning Lab.

anchorOrg/Admin level webhooks
anchor

Admins 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. They 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. Integrations acting on-behalf of an admin need to have the Admin level scope to register org wide webhooks.

anchorWebex Webhooks
anchor

You can use the Webex API to create a new webhook, to update an existing webhook, or to delete a webhook once it's no longer needed.

When you create a webhook for a particular event, the notification data will be sent as an HTTP POST, in JSON format, to a URL of your choosing, each time it is triggered. Please note, that this URL must be publicly reachable and Internet-accessible by Webex, where your application will be listening for inbound HTTP requests. A response is also required from the web server for delivery. If Webex does not receive a successful HTTP response in the 2xx range from the server, your webhook will be disabled after 100 failed attempts within a five minute period.

In order to create a webhook for a resource, make sure that the auth token has a read scope for that resource. For example, to create a webhook that receives messages, the application must have the spark:messages_read scope enabled. Likewise, to create a webhook for notification of membership changes to a room, the application must have the spark:memberships_read scope. For more information on auth scopes and how to enable them, see Scopes.

anchorFiltering Webhooks
anchor

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 the roomId or roomType 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.

For a list of available filters you can use, see “Resources, Events & Filters” below.

You can only use ID filters for resources you have access to. If you do not have access to a particular resource or ID filter, you will receive an error (such as invalid value for filter: roomId) from the API.

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.

Resources, Events, & Filters

Below is a table of Webex events which webhooks can monitor for a given resource, the actions that will trigger these events, and the various filters you can add to narrow down the specific event notifications you would like to receive. Use an “&” between each filter to combine them.

ResourceEventTriggerFilters (optional)
attachmentActionscreatedA user interacted with one of your cardsmessageId — limit to a particular message, by ID
personId — limit to a particular person, by ID
roomId — limit to a particular room, by ID
membershipscreatedSomeone joined a room that you're in or you've been added to a new roomroomId — limit to a particular room, by ID
personId — limit to a particular person, by ID
personEmail — limit to a particular person, by email
isModerator — limit to moderators of a room
membershipsupdatedSomeone's membership was updated in a room that you're in; primarily used to detect moderator changesroomId — limit to a particular room, by ID
personId — limit to a particular person, by ID
personEmail — limit to a particular person, by email
isModerator — limit to moderators of a room
membershipsdeletedSomeone left or was kicked out of a room that you're in, or you left or were removed from a room; only triggers for group rooms, not 1-to-1 roomsroomId — limit to a particular room, by ID
personId — limit to a particular person, by ID
personEmail — limit to a particular person, by email
isModerator — limit to moderators of a room
messagescreatedNew message posted into a room that you're inroomId — limit to a particular room, by ID
roomType — limit to a particular room type (such as direct or group)
personId — limit to a particular person, by ID
personEmail — limit to a particular person, by email
mentionedPeople — limit to messages which contain these mentioned people, by person ID; accepts me as a shorthand for your own person ID; separate multiple values with commas
hasFiles — limit to messages which contain file content attachments
messagesdeletedA message was deleted from a room that you're inroomId — limit to a particular room, by room ID
roomType — limit to a particular room type (such as direct or group)
personId — limit to a particular person, by ID
personEmail — limit to a particular person, by email
mentionedPeople — limit to messages which contain these mentioned people, by person ID; accepts me as a shorthand for your own person ID; separate multiple values with commas
hasFiles — limit to messages which contain file content attachments
roomscreatedA new room was created by you or one of your integrationstype — limit to a particular room type (such as direct or group)
isLocked — limit to rooms that are locked
roomsupdatedA room that you're in was updated; primarily used to detect when a room becomes Locked or Unlockedtype — limit to a particular room type (such as direct or group)
isLocked — limit to rooms that are locked
telephony_callscreatedYou started (originated) or received a call.personality — limit to a particular call personality (clickToDial, originator, or terminator)
state — limit to a particular call state (alerting, connected, connecting, disconnected, held, or remoteHeld)
address — limit to calls to a particular address or number
personId — limit to a particular person, by ID
callType — limit to a particular call type (emergency, external, location, organization, other, or repair
telephony_callsupdatedA call you started or received, was updated (e.g. call was answered, forwarded, resumed, etc.)personality — limit to a particular call personality (clickToDial, originator, or terminator)
state — limit to a particular call state (alerting, connected, connecting, disconnected, held, or remoteHeld)
address — limit to calls to a particular address or number
personId — limit to a particular person, by ID
callType — limit to a particular call type (emergency, external, location, organization, other, or repair
telephony_callsdeletedA call you started or received, was disconnected (deleted).personality — limit to a particular call personality (clickToDial, originator, or terminator)
state — limit to a particular call state (alerting, connected, connecting, disconnected, held, or remoteHeld)
address — limit to calls to a particular address or number
personId — limit to a particular person, by ID
callType — limit to a particular call type (emergency, external, location, organization, other, or repair
telephony_mwiupdatedYour Webex Calling voicemail messages were updated (e.g. message was received, deleted, marked as read, or marked as unread)
meetingscreatedA new meeting was createdid — Meeting Id
meetingNumber — Meeting number
meetingType — Meeting type
state — Meeting state
hostEmail — Email address for the meeting host
hostUserId — Unique identifier for meeting host
siteUrl — Webex site URL to query
meetingsupdatedA meeting that you're in was updatedid — Meeting Id
meetingNumber — Meeting number
meetingType — Meeting type
state — Meeting state
hostEmail — Email address for the meeting host
hostUserId — Unique identifier for meeting host
siteUrl — Webex site URL to query
meetingsdeletedA meeting that you're in was deletedid — Meeting Id
meetingNumber — Meeting number
meetingType — Meeting type
state — Meeting state
hostEmail — Email address for the meeting host
hostUserId — Unique identifier for meeting host
siteUrl — Webex site URL to query
meetingsstartedA meeting was startedid — Meeting Id
meetingNumber — Meeting number
meetingType — Meeting type
state — Meeting state
hostEmail — Email address for the meeting host
hostUserId — Unique identifier for meeting host
siteUrl — Webex site URL to query
meetingsendedA meeting was endedid — Meeting Id
meetingNumber — Meeting number
meetingType — Meeting type
state — Meeting state
hostEmail — Email address for the meeting host
hostUserId — Unique identifier for meeting host
siteUrl — Webex site URL to query
recordingscreatedA new recording was createdid — Recording Id
meetingId — Unique identifier for the parent meeting series, scheduled meeting or meeting instance for which recordings are being requested
scheduledMeetingId — Unique identifier for the parent scheduled meeting which the recording belongs to
meetingSeriesId — Unique identifier for the parent meeting series which the recording belongs to
hostEmail — Email address for the meeting host
hostUserId — Unique identifier for meeting host
siteUrl — Webex site URL to query
recordingsupdatedA recording that you're in was updatedid — Recording Id
meetingId — Unique identifier for the parent meeting series, scheduled meeting or meeting instance for which recordings are being requested
scheduledMeetingId — Unique identifier for the parent scheduled meeting which the recording belongs to
meetingSeriesId — Unique identifier for the parent meeting series which the recording belongs to
hostEmail — Email address for the meeting host
hostUserId — Unique identifier for meeting host
siteUrl — Webex site URL to query
recordingsdeletedA recording that you're in was deletedid — Recording Id
meetingId — Unique identifier for the parent meeting series, scheduled meeting or meeting instance for which recordings are being requested
scheduledMeetingId — Unique identifier for the parent scheduled meeting which the recording belongs to
meetingSeriesId — Unique identifier for the parent meeting series which the recording belongs to
hostEmail — Email address for the meeting host
hostUserId — Unique identifier for meeting host
siteUrl — Webex site URL to query
meetingParticipantsjoinedA participant has joined the meetingid — Participant Id
meetingId — Meeting Instance Id
hostEmail — Email address for the meeting host
meetingParticipantsleftA participant has left the meetingid — Participant Id
meetingId — Meeting Instance Id
hostEmail — Email address for the meeting host

Telephony_calls and telephony_mwi webhooks only provide notifications for Webex Calling users.

Remember, bots can only see messages in which they're specifically mentioned. See Differences Between Bots & People in the Bots guide for more details.

For more examples of uses for webhooks and filtering, see our blog post Using Webhooks - Rooms, Messages, Memberships and more. For a step-by-step tutorial that shows you how to create a webhook and add filters, see Experiment with Webex Webhooks over in Cisco DevNet.

anchorThe Firehose Webhook
anchor

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 following resources support firehose webhooks: memberships, messages, and rooms.

Single Resource Firehose

A single resource firehose webhook will send a notification for any created/updated/deleted event using all activities as a trigger for a given resource type. 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"
}

Note: The all notably does not yet include any other events but created, updated, deleted. In particular for meetings started/ended and meetingsParticipant joined/left individual webhooks must be registered.

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

Creating a webhook for all resources requires that you have read scopes for all supported resources: memberships, messages, and rooms.

anchorCreating a Webhook
anchor

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
ParameterExplanation
nameA label to remember why it was created. Use it for whatever purpose you'd like.
targetUrlTell Webex where you'd like to receive platform events. See the following Handling Requests from Webex section for detailed information about the webhook request format and best practices for scaling your infrastructure.
resourceIndicates the noun being observed and will generally match the plural form of one of the Webex APIs (i.e. messages).
eventFurther narrows the events by specifying the action that would trigger a notification to your backend.
filterA set of filtering critera. Generally speaking, webhook filters will be a subset of the query parameters available when GETing a list of the target resource. It is an optional property. To add multiple filters, separate them with the “&” symbol. For more information about filters, see Filtering Webhooks.
secretAn optional field used to generate a payload signature. See Handling Requests from Webex for more information.

A valid OAuth token is only required to create a webhook. As long as the webhook receives a successful HTTP response it will run indefinitely, even if the OAuth token has expired. However, since initial webhook notifications only contain metadata and encrypted information, sensitive data will always remain secure. See Handling Requests from Webex for more information.

anchorUser Level Scopes for Meeting Related Webhooks
anchor

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

ScopeResourceUsage
meeting:schedules_readmeetingsManipulate webhooks of meetings resource as a normal user
meeting:participants_readmeetingParticipantsManipulate webhooks of meetingParticipants resource as a normal user
meeting:recordings_readrecordingsManipulate webhooks of recordings resource as a normal user
anchorAdmin/Organization Level Scopes for Meeting Related Webhooks
anchor

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

ScopeResourceUsage
meeting:admin_schedule_readmeetingsManipulate webhooks of meetings resource as an admin
meeting:admin_participants_readmeetingParticipantsManipulate webhooks of meetingParticipants resource as an admin
meeting:admin_recordings_readrecordingsManipulate webhooks of recordings resource as an admin
anchorHandling Requests from Webex
anchor

When one of your webhooks is triggered by an event, Webex will send an HTTP POST to the backend targetUrl that you've specified. The body of the POST will look something like this:

{
  "id": "Y2lzY29zcGFyazovL3VzL1dFQkhPT0svZjRlNjA1NjAtNjYwMi00ZmIwLWEyNWEtOTQ5ODgxNjA5NDk3",
  "name": "New message in 'Project Unicorn' room",
  "resource": "messages",
  "event": "created",
  "filter": "roomId=Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
  "orgId": "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
  "createdBy": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
  "appId": "Y2lzY29zcGFyazovL3VzL0FQUExJQ0FUSU9OL0MyNzljYjMwYzAyOTE4MGJiNGJkYWViYjA2MWI3OTY1Y2RhMzliNjAyOTdjODUwM2YyNjZhYmY2NmM5OTllYzFm",
  "ownedBy": "creator",
  "status": "active",
  "actorId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
  "data":{
    "id": "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvOTJkYjNiZTAtNDNiZC0xMWU2LThhZTktZGQ1YjNkZmM1NjVk",
    "roomId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
    "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
    "personEmail": "matt@example.com",
    "created": "2015-10-18T14:26:16.000Z"
  }
}

The first few properties shown above are called the “envelope.” They identify all webhooks that are sent. This envelope contains the following information:

ParameterExplanation
idThe webhook ID. This is the same ID returned when you created the webhook and is what you would use to view the webhook configuration or delete the webhook.
nameThe name you gave your webhook when you created it.
resourceThe resource the webhook data is about.
eventThe type of event this webhook is for.
filterLists any filters that you applied that triggered this webhook.
orgIdThe organization that owns the webhook. This usually is the organization the user that added the webhook belongs to. This ID can be used to view the Organization details with the API.
createdByThe personId of the user that added the webhook.
appIdThe ID of the Webex app that was used to create the webhook. This could be one of your apps, an app from the Webex App Hub, a privately developed app, or this Webex for Developers site if the webhook was created with your personal access token.
ownedByIndicates if the webhook is owned by the org or the creator. Webhooks owned by the creator can only receive events that are accessible to the creator of the webhook. Those owned by the organization will receive events that are visible to anyone in the organization.
statusIndicates if the webhook is active. A webhook that cannot reach your URL is disabled. Thus, for all webhooks you receive, the status will always read ‘active.’
actorIdThe personId of the user that caused the webhook to be sent. For example, on a messsage created webhook, the author of the message will be the actor. On a membership deleted webhook, the actor is the person who removed a user from a room.
dataContains the JSON representation of the resource that triggered the webhook. Note: the data property's id is not the same ID as the webhook ID.
Using the Data Property

The webhook's data property contains the JSON representation of the resource event that triggered the webhook. For example, if you created a webhook that triggers when messages are created (i.e. posted into a room), then the data property will contain the JSON representation for a message resource, as specified in the Messages API documentation. Likewise, if you created a webhook that triggers when telephony_calls are created (i.e. a call is originated or received), then the data property will contain the JSON representation for a telephony_calls resource, as specified in the Call-Control API documentation.

If the webhook's resource event contains sensitive data, the data property will only contain “metadata” about the event. See "Handling Sensitive Data" below for more information about how to retrieve the entire resource.

Handling Sensitive Data

Webex encrypts sensitive room content such as titles and message text using keys only available to the members of that room. This means that not even the Webex operations team can read your messages, making it one of the most secure communications platforms on the planet. This level of security has a subtle impact on webhooks.

You'll notice in the above message webhook example that the text property is missing. That's because room messages are considered sensitive information and since Webex initiated the request to your backend, it did not have your Access Token with which to decrypt the message. In order to get the sensitive information, your app needs to use the resource id to fetch the full resource. Using the above messages example, your app could fetch the complete message object along with the text by doing an authenticated (via your Bearer Token) GET request to /messages/{id} as shown below:

GET https://webexapis.com/v1/messages/Y2lzY29zcGFyazovL3VzL01FU1NBR0UvMzIzZWUyZjAtOWFhZC0xMWU1LTg1YmYtMWRhZjhkNDJlZjlj

{
  "id": "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvMzIzZWUyZjAtOWFhZC0xMWU1LTg1YmYtMWRhZjhkNDJlZjlj",
  "roomId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
  "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
  "personEmail": "matt@example.com",
  "text": "Something interesting and potentially sensitive",
  "created": "2015-12-04T17:33:56.767Z"
}
Authenticating Requests

Webhooks require that the Webex Cloud be able to reach your backend over HTTP. One common question from enterprise IT is how to authenticate that a request is coming from Cisco. We are continuously adding infrastructure to the Webex Cloud so only listing IPs that are allowed is not practical. To solve this, we introduced a technique for cryptographically verifying the JSON payload based on a shared secret of your choosing.

When creating a webhook you can now supply a secret parameter. If specified, every message sent to your backend will contain a new HTTP header called X-Spark-Signature containing an HMAC-SHA1 signature of the JSON payload.

The secret parameter can be specified when creating a webhook.

anchorDisabled Webhooks
anchor

A webhook's targetUrl specifies the server endpoint that will receive the webhook payload. If Webex attempts to deliver 100 webhook notifications within five minutes and the server either becomes unreachable or does not respond with a successful HTTP code in the 2xx range, the webhook will be disabled. Once a webhook is disabled, it will not be reenabled automatically.

To see the current status of a webhook, use the Get Webhook Details API endpoint. To reactivate a disabled webhook, use the Update a Webhook API endpoint with the status parameter set to ‘active’.

Before reenabling a disabled webhook, ensure that any issues which prevented successful delivery have been corrected. Webhooks reenabled within five minutes of being automatically disabled will have a lower threshold for delivery problems. During this period, if the server becomes unreachable or does not respond with a successful HTTP code, the webhook will be immediately disabled again.