openapi: 3.1.0
info:
  title: Cisco Webex Webhooks API
  description: >-
    Register webhooks to receive real-time HTTP callbacks when specific events
    occur in Webex. Supports filtering by resource type, event type, and
    other criteria for efficient event-driven integrations.
  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:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Webex API access token. Obtain via OAuth 2.0 authorization flow or
        personal access token from developer.webex.com.
  schemas:
    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.
    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.