openapi: 3.0.0
info:
title: Webex Admin Address Book Webhooks API
version: 1.0.0
description: The Webex Admin APIs provide comprehensive programmatic access to administrative functions for managing Webex organizations, users, licenses, and settings. These APIs enable automation of user provisioning, license assignment, compliance management, and audit event retrieval. Administrators can integrate with enterprise identity systems, enforce security policies, monitor usage, and streamline onboarding/offboarding processes. The APIs support granular control over organizational resources, making them ideal for large-scale deployments and custom admin tooling.
tags:
- name: Webhooks
paths:
/webhooks:
get:
responses:
'200':
description: OK
headers:
Link:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookCollectionResponse'
example:
items:
- id: Y2lzY29zcGFyazovL3VzL1dFQkhPT0svOTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh
name: My Awesome Webhook
targetUrl: https://example.com/mywebhook
resource: messages
event: created
filter: roomId=Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0
secret: 86dacc007724d8ea666f88fc77d918dad9537a15
status: active
created: '2015-10-18T14:26:16+00:00'
ownedBy: org
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: List Webhooks
operationId: List Webhooks
description: List all of your webhooks.
tags:
- Webhooks
parameters:
- name: max
in: query
description: Limit the maximum number of webhooks in the response.
example: '100'
schema:
type: number
default: 100
- name: ownedBy
in: query
description: Limit the result list to org wide webhooks. Only allowed value is `org`.
example: org
schema:
type: string
post:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
example:
id: Y2lzY29zcGFyazovL3VzL1dFQkhPT0svOTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh
name: My Awesome Webhook
targetUrl: https://example.com/mywebhook
resource: messages
event: created
filter: roomId=Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0
secret: 86dacc007724d8ea666f88fc77d918dad9537a15
status: active
created: '2015-10-18T14:26:16+00:00'
ownedBy: org
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: Create a Webhook
operationId: Create a Webhook
description: 'Creates a webhook.
To learn more about how to create and use webhooks, see The [Webhooks Guide](/docs/api/guides/webhooks).'
tags:
- Webhooks
parameters: []
requestBody:
content:
application/json:
example:
name: My Awesome Webhook
targetUrl: https://example.com/mywebhook
resource: messages
event: created
filter: roomId=Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0
secret: 86dacc007724d8ea666f88fc77d918dad9537a15
ownedBy: org
schema:
type: object
required:
- name
- targetUrl
- resource
- event
properties:
name:
type: string
example: My Awesome Webhook
description: A user-friendly name for the webhook.
targetUrl:
type: string
example: https://example.com/mywebhook
description: URL that receives POST requests for each event.
resource:
type: string
enum:
- attachmentActions
- dataSources
- memberships
- messages
- rooms
- meetings
- recordings
- convergedRecordings
- meetingParticipants
- meetingTranscripts
- telephony_calls
- telephony_conference
- telephony_mwi
- uc_counters
- serviceApp
- adminBatchJobs
description: "Resource type for the webhook. Creating a webhook requires 'read' scope on the resource the webhook is for.\n * `attachmentActions` - [Attachment Actions](/docs/api/v1/attachment-actions) resource.\n * `dataSources` - [data sources](/docs/api/v1/data-sources) resource.\n * `memberships` - [Memberships](/docs/api/v1/memberships) resource.\n * `messages` - [Messages](/docs/api/v1/messages) resource.\n * `rooms` - [Rooms](/docs/api/v1/rooms) resource.\n * `meetings` - [Meetings](/docs/api/v1/meetings) resource.\n * `recordings` - [Recordings](/docs/api/v1/recordings) resource.\n * `convergedRecordings` - [CallRecordings](/docs/api/v1/converged-recordings) resource.\n * `meetingParticipants` - [Meeting Participants](/docs/api/v1/meeting-participants) resource.\n * `meetingTranscripts` - [Meeting Transcripts](/docs/api/v1/meeting-transcripts) resource.\n * `telephony_calls` - [Webex Calling](/docs/webex-calling-overview) call resources.\n * `telephony_conference` - [Webex Calling](/docs/webex-calling-overview) conference controls resource.\n * `telephony_mwi` - [Webex Calling](/docs/webex-calling-overview) voicemail message waiting indicator resource.\n * `uc_counters` - Performance counter for a dedicated instance.\n * `serviceApp` - Service App authorization notification.\n * `adminBatchJobs` - Admin Batch Jobs notification.\n"
event:
type: string
enum:
- created
- updated
- deleted
- started
- ended
- joined
- left
- migrated
- authorized
- deauthorized
- statusChanged
description: "Event type for the webhook.\n * `created` - An object is created.\n * `updated` - An object is updated.\n * `deleted` - An object is deleted.\n * `started` - A meeting is started.\n * `ended` - A meeting is ended.\n * `joined` - A participant joined.\n * `left` - A participant left.\n * `migrated` - A room was migrated to a different geography. The roomId has changed.\n * `authorized` - A Service App was authorized.\n * `deauthorized` - A Service App was deauthorized.\n * `statusChanged` - Status of admin batch job was changed.\n"
filter:
type: string
example: roomId=Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0
description: Filter that defines the webhook scope. See [Filtering Webhooks](/docs/api/guides/webhooks#filtering-webhooks) for more information. Please note that if a filter of `hostEmail`, `hostUserId`, `ownerEmail` or `ownerId` is specified, `ownedBy` must be set to `org`.
secret:
type: string
example: 86dacc007724d8ea666f88fc77d918dad9537a15
description: Secret used to generate payload signature.
ownedBy:
type: string
example: org
description: Specify `org` when creating an org/admin level webhook. Supported for `meetings`, `recordings`, `convergedRecordings`,`meetingParticipants`, `meetingTranscripts`, `videoMeshAlerts`, `controlHubAlerts`, `rooms`, `messaging` and `adminBatchJobs` (for Compliance Officers and messages with file attachments only - see [inline file DLP](/docs/api/guides/webex-real-time-file-dlp-basics)) resources.
/webhooks/{webhookId}:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
example:
id: Y2lzY29zcGFyazovL3VzL1dFQkhPT0svOTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh
name: My Awesome Webhook
targetUrl: https://example.com/mywebhook
resource: messages
event: created
filter: roomId=Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0
secret: 86dacc007724d8ea666f88fc77d918dad9537a15
status: active
created: '2015-10-18T14:26:16+00:00'
ownedBy: org
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: Get Webhook Details
operationId: Get Webhook Details
description: 'Shows details for a webhook, by ID.
Specify the webhook ID in the `webhookId` parameter in the URI.'
tags:
- Webhooks
parameters:
- name: webhookId
in: path
description: The unique identifier for the webhook.
required: true
example: Y2lzY29zcGFyazovL3VzL1dFQkhPT0svOTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh
schema:
type: string
put:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
example:
id: Y2lzY29zcGFyazovL3VzL1dFQkhPT0svOTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh
name: My Awesome Webhook
targetUrl: https://example.com/mywebhook
resource: messages
event: created
filter: roomId=Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0
secret: 86dacc007724d8ea666f88fc77d918dad9537a15
status: active
created: '2015-10-18T14:26:16+00:00'
ownedBy: org
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: Update a Webhook
operationId: Update a Webhook
description: 'Updates a webhook, by ID. You cannot use this call to deactivate a webhook, only to activate a webhook that was auto deactivated.
The fields that can be updated are `name`, `targetURL`, `secret` and `status`. All other fields, if supplied, are ignored.
Specify the webhook ID in the `webhookId` parameter in the URI.'
tags:
- Webhooks
parameters:
- name: webhookId
in: path
description: The unique identifier for the webhook.
required: true
example: Y2lzY29zcGFyazovL3VzL1dFQkhPT0svOTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh
schema:
type: string
requestBody:
content:
application/json:
example:
name: My Awesome Webhook
targetUrl: https://example.com/mywebhook
secret: 86dacc007724d8ea666f88fc77d918dad9537a15
ownedBy: org
status: active
schema:
type: object
required:
- name
- targetUrl
properties:
name:
type: string
example: My Awesome Webhook
description: A user-friendly name for the webhook.
targetUrl:
type: string
example: https://example.com/mywebhook
description: URL that receives POST requests for each event.
secret:
type: string
example: 86dacc007724d8ea666f88fc77d918dad9537a15
description: Secret used to generate payload signature.
ownedBy:
type: string
example: org
description: Specify `org` when creating an org/admin level webhook. Supported for `meetings`, `recordings`, `convergedRecordings`, `meetingParticipants`, `meetingTranscripts`, `videoMeshAlerts`, `controlHubAlerts`, `rooms`, `messaging` and `adminBatchJobs` (for Compliance Officers and messages with file attachments only - see [inline file DLP](/docs/api/guides/webex-real-time-file-dlp-basics)) resources.
status:
type: string
enum:
- active
description: Status of the webhook. Use "active" to reactivate a disabled webhook.
delete:
responses:
'204':
description: No Content
headers: {}
content: {}
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: Delete a Webhook
operationId: Delete a Webhook
description: 'Deletes a webhook, by ID.
Specify the webhook ID in the `webhookId` parameter in the URI.'
tags:
- Webhooks
parameters:
- name: webhookId
in: path
description: The unique identifier for the webhook.
required: true
example: Y2lzY29zcGFyazovL3VzL1dFQkhPT0svOTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh
schema:
type: string
components:
schemas:
Webhook:
type: object
properties:
id:
type: string
example: Y2lzY29zcGFyazovL3VzL1dFQkhPT0svOTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh
description: A unique identifier for the webhook.
name:
type: string
example: My Awesome Webhook
description: A user-friendly name for the webhook.
targetUrl:
type: string
example: https://example.com/mywebhook
description: URL that receives POST requests for each event.
resource:
type: string
enum:
- attachmentActions
- dataSources
- memberships
- messages
- rooms
- meetings
- recordings
- convergedRecordings
- meetingParticipants
- meetingTranscripts
- telephony_calls
- telephony_conference
- telephony_mwi
- uc_counters
- serviceApp
- adminBatchJobs
description: "Resource type for the webhook. Creating a webhook requires 'read' scope on the resource the webhook is for.\n * `attachmentActions` - [Attachment Actions](/docs/api/v1/attachment-actions) resource.\n * `dataSources` - [data sources](/docs/api/v1/data-sources) resource.\n * `memberships` - [Memberships](/docs/api/v1/memberships) resource.\n * `messages` - [Messages](/docs/api/v1/messages) resource.\n * `rooms` - [Rooms](/docs/api/v1/rooms) resource.\n * `meetings` - [Meetings](/docs/api/v1/meetings) resource.\n * `recordings` - [Recordings](/docs/api/v1/recordings) resource.\n * `convergedRecordings` - [CallRecordings](/docs/api/v1/converged-recordings) resource.\n * `meetingParticipants` - [Meeting Participants](/docs/api/v1/meeting-participants) resource.\n * `meetingTranscripts` - [Meeting Transcripts](/docs/api/v1/meeting-transcripts) resource.\n * `telephony_calls` - [Webex Calling](/docs/webex-calling-overview) call resources.\n * `telephony_conference` - [Webex Calling](/docs/webex-calling-overview) conference controls resource.\n * `telephony_mwi` - [Webex Calling](/docs/webex-calling-overview) voicemail message waiting indicator resource.\n * `uc_counters` - Performance counter for a dedicated instance.\n * `serviceApp` - Service App authorization notification.\n * `adminBatchJobs` - Admin Batch Jobs notification.\n"
event:
type: string
enum:
- created
- updated
- deleted
- started
- ended
- joined
- left
- migrated
- authorized
- deauthorized
- statusChanged
description: "Event type for the webhook.\n * `created` - An object was created.\n * `updated` - An object was updated.\n * `deleted` - An object was deleted.\n * `started` - A meeting was started.\n * `ended` - A meeting was ended.\n * `joined` - A participant joined.\n * `left` - A participant left.\n * `migrated` - A room was migrated to a different geography. The roomId has changed.\n * `authorized` - A Service App was authorized.\n * `deauthorized` - A Service App was deauthorized.\n * `statusChanged` - Status of admin batch job was changed.\n"
filter:
type: string
example: roomId=Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0
description: Filter that defines the webhook scope.
secret:
type: string
example: 86dacc007724d8ea666f88fc77d918dad9537a15
description: Secret used to generate payload signature.
status:
type: string
enum:
- active
- inactive
description: "Status of the webhook. Use `active` to reactivate a disabled webhook.\n * `active` - Webhook is active.\n * `inactive` - Webhook is inactive.\n"
created:
type: string
example: '2015-10-18T14:26:16+00:00'
description: Date and time the webhook was created.
ownedBy:
type: string
example: org
description: Specify `org` when creating an org/admin level webhook. Supported for `meetings`, `recordings`, `convergedRecordings`, `meetingParticipants`, `meetingTranscripts`, `videoMeshAlerts`, `controlHubAlerts`, `rooms`, `messaging` and `adminBatchJobs` (for Compliance Officers and messages with file attachments only - see [inline file DLP](/docs/api/guides/webex-real-time-file-dlp-basics)) resources.
WebhookCollectionResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Webhook'
securitySchemes:
oauth2:
flows:
authorizationCode:
authorizationUrl: /
scopes: {}
tokenUrl: /
type: oauth2
bearer-key:
type: http
description: e.g. Bearer YOUR_AUTHORIZATION_TOKEN
scheme: bearer
bearerFormat: JWT
bearerAuth:
type: oauth2
description: OAuth 2.0 Bearer token authentication
flows:
authorizationCode:
authorizationUrl: https://webexapis.com/v1/authorize
tokenUrl: https://webexapis.com/v1/access_token
scopes:
spark:applications_token: Create access tokens for Service Apps