Cisco Webex Webhooks API

openapi: 3.1.0
info:
  title: Cisco Webex Admin Audit Events Webhooks API
  description: Access admin audit events for tracking administrative actions performed in Webex Control Hub. Available to full administrators for compliance monitoring and security auditing purposes.
  version: 1.0.0
  contact:
    name: Cisco Webex Developer Support
    url: https://developer.webex.com/support
  license:
    name: Cisco Webex API Terms of Service
    url: https://developer.webex.com/terms-of-service
servers:
- url: https://webexapis.com/v1
  description: Webex Production API
security:
- bearerAuth: []
tags:
- name: Webhooks
  description: Operations for managing webhooks
paths:
  /webhooks:
    get:
      operationId: listWebhooks
      summary: Cisco Webex List Webhooks
      description: Lists all webhooks registered by the authenticated user. Results are paginated and include webhook status and configuration details.
      tags:
      - Webhooks
      parameters:
      - name: max
        in: query
        description: Maximum number of webhooks to return (default 100).
        schema:
          type: integer
          default: 100
      - name: ownedBy
        in: query
        description: Filter webhooks by ownership. Set to 'org' for organization-level webhooks.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with list of webhooks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
        '401':
          description: Unauthorized - invalid or missing access token.
    post:
      operationId: createWebhook
      summary: Cisco Webex Create a Webhook
      description: Creates a new webhook. Webhooks receive HTTP POST requests when the specified resource and event combination occurs. A secret can be provided for payload signature verification.
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '200':
          description: Webhook created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Bad request - invalid input parameters.
        '401':
          description: Unauthorized - invalid or missing access token.
  /webhooks/{webhookId}:
    get:
      operationId: getWebhookDetails
      summary: Cisco Webex Get Webhook Details
      description: Shows details for a webhook by ID. Returns the webhook configuration, status, and metadata.
      tags:
      - Webhooks
      parameters:
      - name: webhookId
        in: path
        required: true
        description: Unique identifier for the webhook.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with webhook details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '404':
          description: Webhook not found.
    put:
      operationId: updateWebhook
      summary: Cisco Webex Update a Webhook
      description: Updates a webhook by ID. Allows changing the name, target URL, secret, status, and ownership of the webhook.
      tags:
      - Webhooks
      parameters:
      - name: webhookId
        in: path
        required: true
        description: Unique identifier for the webhook.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        '200':
          description: Webhook updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Bad request - invalid input parameters.
        '404':
          description: Webhook not found.
    delete:
      operationId: deleteWebhook
      summary: Cisco Webex Delete a Webhook
      description: Deletes a webhook by ID. The webhook will no longer receive notifications for the configured resource and event.
      tags:
      - Webhooks
      parameters:
      - name: webhookId
        in: path
        required: true
        description: Unique identifier for the webhook.
        schema:
          type: string
      responses:
        '204':
          description: Webhook deleted successfully.
        '404':
          description: Webhook not found.
components:
  schemas:
    CreateWebhookRequest:
      type: object
      required:
      - name
      - targetUrl
      - resource
      - event
      properties:
        name:
          type: string
          description: A user-friendly name for the webhook.
        targetUrl:
          type: string
          format: uri
          description: The URL to receive webhook POST requests.
        resource:
          type: string
          description: The resource type to monitor.
          enum:
          - messages
          - rooms
          - memberships
          - meetings
          - recordings
          - meetingParticipants
          - meetingTranscripts
          - attachmentActions
          - telephony_calls
        event:
          type: string
          description: The event type to monitor.
          enum:
          - created
          - updated
          - deleted
          - started
          - ended
          - joined
          - left
          - migrated
          - read
        filter:
          type: string
          description: Filter expression to narrow webhook scope.
        secret:
          type: string
          description: Secret for payload signature verification.
        ownedBy:
          type: string
          description: Set to 'org' for organization-level webhooks.
    UpdateWebhookRequest:
      type: object
      required:
      - name
      - targetUrl
      properties:
        name:
          type: string
          description: Updated name for the webhook.
        targetUrl:
          type: string
          format: uri
          description: Updated target URL for the webhook.
        secret:
          type: string
          description: Updated secret for payload signatures.
        status:
          type: string
          description: Updated webhook status.
          enum:
          - active
          - inactive
        ownedBy:
          type: string
          description: Updated ownership type.
    Webhook:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the webhook.
        name:
          type: string
          description: A user-friendly name for the webhook.
        targetUrl:
          type: string
          format: uri
          description: The URL that receives the webhook POST requests.
        resource:
          type: string
          description: The resource type for the webhook.
          enum:
          - messages
          - rooms
          - memberships
          - meetings
          - recordings
          - meetingParticipants
          - meetingTranscripts
          - attachmentActions
          - telephony_calls
        event:
          type: string
          description: The event type for the webhook.
          enum:
          - created
          - updated
          - deleted
          - started
          - ended
          - joined
          - left
          - migrated
          - read
        filter:
          type: string
          description: The filter expression for the webhook scope.
        secret:
          type: string
          description: Secret for generating webhook payload signatures.
        status:
          type: string
          description: The current status of the webhook.
          enum:
          - active
          - inactive
        ownedBy:
          type: string
          description: Webhook ownership type.
        orgId:
          type: string
          description: Organization ID of the webhook owner.
        createdBy:
          type: string
          description: Person ID of the webhook creator.
        appId:
          type: string
          description: Application ID associated with the webhook.
        created:
          type: string
          format: date-time
          description: Date and time the webhook was created.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Webex API access token. Obtain via OAuth 2.0 authorization flow. Requires audit:events_read scope.