Composio Webhook Subscriptions API

openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform Account Management Webhook Subscriptions API
  description: Webhook delivery subscriptions. Outbound URLs Composio posts trigger events to, plus signing secret rotation and event-type filters.
  contact:
    name: Composio Support
    url: https://composio.dev/support
    email: support@composio.dev
  license:
    name: Proprietary
    url: https://composio.dev/terms
servers:
- url: https://backend.composio.dev
  description: PRODUCTION API
tags:
- name: Webhook Subscriptions
  description: Webhook delivery subscriptions. Outbound URLs Composio posts trigger events to, plus signing secret rotation and event-type filters.
paths:
  /api/v3/webhook_subscriptions:
    post:
      summary: Create webhook subscription
      description: Creates a webhook subscription for the authenticated project. Only one subscription is allowed per project. The signing secret is returned in subscription responses.
      tags:
      - Webhook Subscriptions
      operationId: postWebhookSubscriptions
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_url:
                  type: string
                  maxLength: 2048
                  format: uri
                  description: HTTPS URL to receive webhook events
                enabled_events:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  description: Array of event types to subscribe to
                version:
                  type: string
                  enum:
                  - V1
                  - V2
                  - V3
                  default: V3
                  description: Webhook payload version
              required:
              - webhook_url
              - enabled_events
      responses:
        '201':
          description: Webhook subscription created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: webhookSubscriptionId
                    description: Unique subscription ID
                  webhook_url:
                    type: string
                    description: Webhook destination URL
                  version:
                    type: string
                    enum:
                    - V1
                    - V2
                    - V3
                    description: Webhook payload version
                  enabled_events:
                    type: array
                    items:
                      type: string
                    description: Subscribed event types
                  secret:
                    type: string
                    description: Signing secret for HMAC verification
                  created_at:
                    type: string
                    description: ISO 8601 timestamp
                  updated_at:
                    type: string
                    description: ISO 8601 timestamp
                required:
                - id
                - webhook_url
                - version
                - enabled_events
                - secret
                - created_at
                - updated_at
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Subscription already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List webhook subscriptions
      description: Lists all webhook subscriptions for the authenticated project with pagination. Currently limited to one subscription per project.
      tags:
      - Webhook Subscriptions
      operationId: getWebhookSubscriptions
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: number
          nullable: true
        required: false
        description: Number of items per page, max allowed is 1000
        name: limit
        in: query
      - schema:
          type: string
        required: false
        description: Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.
        name: cursor
        in: query
      responses:
        '200':
          description: Webhook subscriptions retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: webhookSubscriptionId
                          description: Unique subscription ID
                        webhook_url:
                          type: string
                          description: Webhook destination URL
                        version:
                          type: string
                          enum:
                          - V1
                          - V2
                          - V3
                          description: Webhook payload version
                        enabled_events:
                          type: array
                          items:
                            type: string
                          description: Subscribed event types
                        secret:
                          type: string
                          description: Signing secret for HMAC verification
                        created_at:
                          type: string
                          description: ISO 8601 timestamp
                        updated_at:
                          type: string
                          description: ISO 8601 timestamp
                      required:
                      - id
                      - webhook_url
                      - version
                      - enabled_events
                      - secret
                      - created_at
                      - updated_at
                  next_cursor:
                    type: string
                    nullable: true
                  total_pages:
                    type: number
                  current_page:
                    type: number
                  total_items:
                    type: number
                required:
                - items
                - total_pages
                - current_page
                - total_items
        '400':
          description: Invalid pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/webhook_subscriptions/{id}:
    get:
      summary: Get webhook subscription
      description: Retrieves a webhook subscription by ID.
      tags:
      - Webhook Subscriptions
      operationId: getWebhookSubscriptionsById
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
          format: webhookSubscriptionId
          description: Webhook subscription ID
        required: true
        description: Webhook subscription ID
        name: id
        in: path
      responses:
        '200':
          description: Webhook subscription retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: webhookSubscriptionId
                    description: Unique subscription ID
                  webhook_url:
                    type: string
                    description: Webhook destination URL
                  version:
                    type: string
                    enum:
                    - V1
                    - V2
                    - V3
                    description: Webhook payload version
                  enabled_events:
                    type: array
                    items:
                      type: string
                    description: Subscribed event types
                  secret:
                    type: string
                    description: Signing secret for HMAC verification
                  created_at:
                    type: string
                    description: ISO 8601 timestamp
                  updated_at:
                    type: string
                    description: ISO 8601 timestamp
                required:
                - id
                - webhook_url
                - version
                - enabled_events
                - secret
                - created_at
                - updated_at
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Subscription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      summary: Update webhook subscription
      description: Updates a webhook subscription. At least one field must be provided.
      tags:
      - Webhook Subscriptions
      operationId: patchWebhookSubscriptionsById
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
          format: webhookSubscriptionId
          description: Webhook subscription ID
        required: true
        description: Webhook subscription ID
        name: id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_url:
                  type: string
                  maxLength: 2048
                  format: uri
                  description: HTTPS URL to receive webhook events
                enabled_events:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  description: Array of event types to subscribe to
                version:
                  type: string
                  enum:
                  - V1
                  - V2
                  - V3
                  description: Webhook payload version
      responses:
        '200':
          description: Webhook subscription updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: webhookSubscriptionId
                    description: Unique subscription ID
                  webhook_url:
                    type: string
                    description: Webhook destination URL
                  version:
                    type: string
                    enum:
                    - V1
                    - V2
                    - V3
                    description: Webhook payload version
                  enabled_events:
                    type: array
                    items:
                      type: string
                    description: Subscribed event types
                  secret:
                    type: string
                    description: Signing secret for HMAC verification
                  created_at:
                    type: string
                    description: ISO 8601 timestamp
                  updated_at:
                    type: string
                    description: ISO 8601 timestamp
                required:
                - id
                - webhook_url
                - version
                - enabled_events
                - secret
                - created_at
                - updated_at
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Subscription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete webhook subscription
      description: Permanently deletes a webhook subscription. This action cannot be undone.
      tags:
      - Webhook Subscriptions
      operationId: deleteWebhookSubscriptionsById
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
          format: webhookSubscriptionId
          description: Webhook subscription ID
        required: true
        description: Webhook subscription ID
        name: id
        in: path
      responses:
        '200':
          description: Webhook subscription deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                required:
                - success
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Subscription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/webhook_subscriptions/{id}/rotate_secret:
    post:
      summary: Rotate webhook secret
      description: Generates a new signing secret for the webhook subscription.
      tags:
      - Webhook Subscriptions
      operationId: postWebhookSubscriptionsByIdRotateSecret
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
          format: webhookSubscriptionId
          description: Webhook subscription ID
        required: true
        description: Webhook subscription ID
        name: id
        in: path
      responses:
        '200':
          description: Webhook secret rotated
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: webhookSubscriptionId
                    description: Subscription ID
                  secret:
                    type: string
                    description: New signing secret
                required:
                - id
                - secret
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Subscription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/webhook_subscriptions/event_types:
    get:
      summary: List available event types
      description: Returns all event types that can be subscribed to, along with their supported webhook versions.
      tags:
      - Webhook Subscriptions
      operationId: getWebhookSubscriptionsEventTypes
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      responses:
        '200':
          description: Event types retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        event_type:
                          type: string
                          description: Event type identifier
                        description:
                          type: string
                          description: Human-readable description of the event
                        supported_versions:
                          type: array
                          items:
                            type: string
                            enum:
                            - V1
                            - V2
                            - V3
                          description: Webhook versions that support this event
                      required:
                      - event_type
                      - description
                      - supported_versions
                required:
                - items
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: number
            slug:
              type: string
            status:
              type: number
            request_id:
              type: string
            suggested_fix:
              type: string
            errors:
              type: array
              items:
                type: string
          required:
          - message
          - code
          - slug
          - status
      required:
      - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Project API key authentication
    UserApiKeyAuth:
      type: apiKey
      in: header
      name: x-user-api-key
      description: User API key authentication
    CookieAuth:
      type: apiKey
      in: cookie
      name: authToken
      description: Cookie-based session authentication
    OrgApiKeyAuth:
      type: apiKey
      in: header
      name: x-org-api-key
      description: Organization API key authentication