Corebee Webhooks API

Outbound event webhooks

GitHub OpenAPI

Operations 5

GET /webhooks List webhooks #
POST /webhooks Create a webhook #
GET /webhooks/{id} Get a webhook #
PUT /webhooks/{id} Update a webhook #
DELETE /webhooks/{id} Delete a webhook #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/corebee-ai:corebee-ai-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

corebee-ai-webhooks-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Corebee Ai Webhooks API
  version: 1.0.0
  contact:
    name: Corebee
    email: support@corebee.ai
  description: 'Operations tagged webhooks across 2 of this provider''s published API definitions: corebee-ai-openapi.json, corebee-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://corebee.ai/api/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Webhooks
  description: Outbound event webhooks
paths:
  /webhooks:
    get:
      summary: List webhooks
      operationId: list_webhooks
      tags:
      - Webhooks
      parameters:
      - name: limit
        in: query
        required: false
        description: Page size (max 100, default 25).
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of records to skip.
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
                  meta:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Invalid or missing credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a webhook
      operationId: create_webhook
      tags:
      - Webhooks
      description: Requires url and a non-empty events array. A signing secret is auto-generated (and stored encrypted) when not supplied.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
            example:
              url: https://example.com/hooks/corebee
              events:
              - conversation.created
              - message.created
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Webhook'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://corebee.ai/api/v1
      description: Production
  /webhooks/{id}:
    get:
      summary: Get a webhook
      operationId: get_webhook
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        description: Resource UUID.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Webhook'
        '401':
          description: Invalid or missing credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a webhook
      operationId: update_webhook
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        description: Resource UUID.
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
            example:
              enabled: false
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Webhook'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a webhook
      operationId: delete_webhook
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        description: Resource UUID.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Deleted
        '401':
          description: Invalid or missing credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://corebee.ai/api/v1
      description: Production
webhooks:
  bridge.dialing:
    post:
      summary: A leg is ringing.
      operationId: webhook_bridge_dialing
      tags:
      - Webhooks
      description: 'Sent when a session enters one of: dialing_business, dialing_consumer. Authenticate it with the HMAC signature described on BridgeWebhookEvent before trusting any field. Respond 2xx as soon as you have durably accepted it; any non-2xx, or a response slower than the per-attempt timeout, is treated as a failure and retried.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BridgeWebhookEvent'
      responses:
        '200':
          description: Accepted. Any 2xx is treated as success.
    servers:
    - url: https://corebee.ai/api/v1
      description: Production
  bridge.human_detected:
    post:
      summary: Answering-machine detection concluded a live human is on the business leg.
      operationId: webhook_bridge_human_detected
      tags:
      - Webhooks
      description: 'Sent when a session enters one of: human. Authenticate it with the HMAC signature described on BridgeWebhookEvent before trusting any field. Respond 2xx as soon as you have durably accepted it; any non-2xx, or a response slower than the per-attempt timeout, is treated as a failure and retried.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BridgeWebhookEvent'
      responses:
        '200':
          description: Accepted. Any 2xx is treated as success.
    servers:
    - url: https://corebee.ai/api/v1
      description: Production
  bridge.bridged:
    post:
      summary: The two legs were joined. This is the billable outcome.
      operationId: webhook_bridge_bridged
      tags:
      - Webhooks
      description: 'Sent when a session enters one of: bridged. Authenticate it with the HMAC signature described on BridgeWebhookEvent before trusting any field. Respond 2xx as soon as you have durably accepted it; any non-2xx, or a response slower than the per-attempt timeout, is treated as a failure and retried.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BridgeWebhookEvent'
      responses:
        '200':
          description: Accepted. Any 2xx is treated as success.
    servers:
    - url: https://corebee.ai/api/v1
      description: Production
  bridge.completed:
    post:
      summary: Terminal. The session finished normally.
      operationId: webhook_bridge_completed
      tags:
      - Webhooks
      description: 'Sent when a session enters one of: completed. Authenticate it with the HMAC signature described on BridgeWebhookEvent before trusting any field. Respond 2xx as soon as you have durably accepted it; any non-2xx, or a response slower than the per-attempt timeout, is treated as a failure and retried.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BridgeWebhookEvent'
      responses:
        '200':
          description: Accepted. Any 2xx is treated as success.
    servers:
    - url: https://corebee.ai/api/v1
      description: Production
  bridge.failed:
    post:
      summary: Terminal, except for the one correction described on bridge.completed.
      operationId: webhook_bridge_failed
      tags:
      - Webhooks
      description: 'Sent when a session enters one of: failed. Authenticate it with the HMAC signature described on BridgeWebhookEvent before trusting any field. Respond 2xx as soon as you have durably accepted it; any non-2xx, or a response slower than the per-attempt timeout, is treated as a failure and retried.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BridgeWebhookEvent'
      responses:
        '200':
          description: Accepted. Any 2xx is treated as success.
    servers:
    - url: https://corebee.ai/api/v1
      description: Production
  bridge.voice_degraded:
    post:
      summary: The voice of a call was degraded (opt-in)
      operationId: webhook_bridge_voice_degraded
      tags:
      - Webhooks
      description: 'Sent at most once per session, and only to organizations that opted in, when the voice of the call could not start or stopped partway through. It is not a state change: `state` and `previous_state` both carry the state the session was in when it happened, and the lifecycle notifications for the same session still arrive as usual. Opt-in: contact us to enable it for your organization; until then it is never sent. Verify it exactly like the lifecycle notifications: recompute the lowercase hex HMAC-SHA256 of the raw request body bytes with your shared secret, compare it in constant time to `x-corebee-signature`, and only then parse the body. `x-corebee-event-type` repeats `type` for routing and is not signed. Dedupe on `event_id`. Respond 2xx as soon as you have durably accepted it; any non-2xx, or a slow response, is treated as a failure and retried from a durable outbox.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BridgeVoiceDegradedEvent'
      responses:
        '200':
          description: Accepted. Any 2xx is treated as success.
    servers:
    - url: https://corebee.ai/api/v1
      description: Production
components:
  schemas:
    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        url:
          type: string
          format: uri
          example: https://example.com/hooks/corebee
        events:
          type: array
          items:
            type: string
          example:
          - conversation.created
          - message.created
        is_active:
          type: boolean
          default: true
        created_at:
          type: string
          format: date-time
    BridgeWebhookEvent:
      type: object
      description: 'The signed JSON body of an outbound bridge notification.


        **SIGNATURE, verify before you parse.** Every POST carries `x-corebee-signature`: the lowercase hex HMAC-SHA256 of the EXACT raw request body bytes, keyed by the shared secret we issued you. Recompute it over the raw bytes, not over a re-serialization of the parsed JSON, key order and whitespace are part of what was signed, and any JSON library that reorders keys will produce a digest that does not match. Compare with a constant-time equality function. A second header, `x-corebee-event-type`, repeats `type` for routing; it is NOT part of the signed string, so never make a trust decision on it.


        ⛔ **The signed string contains no timestamp**, so the signature alone does not prove freshness: a captured request stays verifiable forever. Until that is fixed, dedupe on `event_id` and treat an event whose `session_id` you have already seen in a terminal state as a replay, with one exception: a bridge.bridged or bridge.completed for a session you recorded as bridge.failed with failure_reason business_abandoned_bridge is a late-join correction (see bridge.completed), and is sent at most once per session. We consider this a gap in our scheme and not something you should design around permanently.


        **Ordering and duplicates.** Delivery is at-least-once. `event_id` is stable and unique per transition, dedupe on it. `previous_state` lets you detect an out-of-order arrival: if it does not match the state you last recorded for the session, you received these two out of order. Retries are exponential with a bounded budget per attempt-cycle, and a notification that cannot be delivered inline is retried from a durable outbox, so a slow or briefly-down endpoint does not lose the event.


        Only the fields below are sent. The session metadata bag is never forwarded: it holds internal orchestration keys, so `customer_ref` is the one value of yours that comes back.'
      required:
      - event_id
      - session_id
      - type
      - state
      - previous_state
      - amd_result
      - failure_reason
      - customer_ref
      - occurred_at
      properties:
        event_id:
          type: string
          description: Stable and unique per transition; the idempotency key you dedupe on. Format `vbe_{session_id}_{n}`. In the rare case where the underlying event row could not be persisted we still deliver terminal notices, with the suffix replaced by `s-{state}`, so dedupe on the whole string, and fall back to (session_id, state) if you see that form.
          example: vbe_4021_88213
        session_id:
          type: integer
          example: 4021
        type:
          type: string
          enum:
          - bridge.dialing
          - bridge.human_detected
          - bridge.bridged
          - bridge.completed
          - bridge.failed
          description: 'Semantic event type. CLOSED set: these five and no others.'
          example: bridge.bridged
        state:
          type: string
          enum:
          - created
          - dialing_business
          - ivr_nav
          - amd_verdict
          - human
          - voicemail
          - prep_line
          - converse
          - dialing_consumer
          - bridging
          - bridged
          - completed
          - failed
          description: 'The state just entered. In practice only the delivered states appear here (dialing_business, dialing_consumer, human, bridged, completed, failed); the enum is the full roster so that this field and the one on BridgeStatus deserialize identically. These states are never delivered as a webhook: created, ivr_nav, amd_verdict, voicemail, prep_line, converse, bridging.'
          example: bridged
        previous_state:
          type: string
          enum:
          - created
          - dialing_business
          - ivr_nav
          - amd_verdict
          - human
          - voicemail
          - prep_line
          - converse
          - dialing_consumer
          - bridging
          - bridged
          - completed
          - failed
          description: The state we came from. Use it to detect out-of-order arrivals.
          example: bridging
        amd_result:
          type: string
          nullable: true
          description: Answering-machine detection verdict when one had been reached, else null.
          example: human
        failure_reason:
          type: string
          nullable: true
          description: 'Populated on bridge.failed, null otherwise. An OPEN string, exactly as on BridgeStatus: new reasons are added without a version bump, so do not validate it against a closed list.'
          example: null
        customer_ref:
          type: string
          nullable: true
          description: Your correlation id from metadata.customer_ref at create time, echoed back. Null when you did not send one.
        occurred_at:
          type: string
          format: date-time
          description: When we recorded the transition. This is our clock after webhook processing, not the carrier's clock at the moment the event happened, and it can trail the real instant by seconds under queue lag. Do not difference two of these to compute a call duration.
    BridgeVoiceDegradedEvent:
      type: object
      description: The signed JSON body of the opt-in bridge.voice_degraded notification. Same envelope and same signature as BridgeWebhookEvent, plus `cause` and `voice`.
      required:
      - event_id
      - session_id
      - type
      - state
      - previous_state
      - amd_result
      - failure_reason
      - customer_ref
      - occurred_at
      - cause
      - voice
      properties:
        event_id:
          type: string
          description: 'Stable per session: at most one bridge.voice_degraded is sent for a session. Dedupe on it.'
          example: vbe_4021_voice_degraded
        session_id:
          type: integer
          example: 4021
        type:
          type: string
          enum:
          - bridge.voice_degraded
          example: bridge.voice_degraded
        state:
          type: string
          description: The session state when the voice was degraded. Not a transition.
          example: bridged
        previous_state:
          type: string
          description: Always equal to `state` on this event.
          example: bridged
        amd_result:
          type: string
          nullable: true
          description: Always null on this event.
          example: null
        failure_reason:
          type: string
          nullable: true
          description: Always null on this event.
          example: null
        customer_ref:
          type: string
          nullable: true
          description: Your correlation id from metadata.customer_ref at create time, echoed back. Null when you did not send one.
        occurred_at:
          type: string
          format: date-time
          description: When we recorded the degradation.
          example: '2026-10-23T10:00:31.000Z'
        cause:
          type: string
          enum:
          - voice_unavailable
          - voice_interrupted
          description: '`voice_unavailable`: the voice could not be produced at all, so the call could not speak. `voice_interrupted`: the voice stopped partway through the call after repeated retries.'
          example: voice_unavailable
        voice:
          type: object
          description: The voice you asked for on this call (the `voice` object of POST /voice/bridge, or the profile it named). All null when the call did not carry one.
          required:
          - voice_id
          - source
          - profile_id
          properties:
            voice_id:
              type: string
              nullable: true
              description: The voice id in force for this call, when you set one.
            source:
              type: string
              nullable: true
              enum:
              - request
              - profile
              - null
              description: '`request` when the call carried a voice directly, `profile` when it named a voice profile.'
            profile_id:
              type: string
              nullable: true
              description: The voice profile the call named, when it named one.
    Error:
      type: object
      description: Error envelope. Fields are also mirrored flat at the top level (code, message, status) for backwards compatibility.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              example: validation_error
            message:
              type: string
              example: content is required
            details:
              type: object
              additionalProperties: true
              nullable: true
        code:
          type: string
        message:
          type: string
        status:
          type: integer
          example: 400
    WebhookCreate:
      type: object
      required:
      - url
      - events
      properties:
        url:
          type: string
          format: uri
        events:
          type: array
          minItems: 1
          items:
            type: string
          example:
          - conversation.created
          - message.created
        secret:
          type: string
          description: Optional HMAC signing secret. Auto-generated and stored encrypted when omitted.
        enabled:
          type: boolean
          default: true
    Pagination:
      type: object
      required:
      - total
      - limit
      - offset
      properties:
        total:
          type: integer
          description: Total matching records.
          example: 142
        limit:
          type: integer
          example: 25
        offset:
          type: integer
          example: 0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Org-scoped API key, or an OAuth 2.1 access token (authorization_code + PKCE; see /.well-known/oauth-protected-resource). An API key is minted in the Corebee dashboard under Settings, Developers, API keys, and the SCOPES it carries are chosen at that moment and cannot be widened afterwards, mint a new key instead. Every voice/bridge operation needs the voice:bridge scope. A key without the scope and a key whose organization does not own the number both answer 403 FORBIDDEN; the message distinguishes them ("Missing required scope: voice:bridge" vs "from_number is not a phone number owned by this organization").'
externalDocs:
  description: Machine-readable catalogue of every error code this API emits.
  url: https://corebee.ai/api/v1/error-codes.json
x-refined-from:
- corebee-ai-openapi.json
- corebee-ai-openapi.yml
x-mcp:
  endpoint: https://corebee.ai/api/v1/mcp/stream
  server_card: https://corebee.ai/.well-known/mcp/server-card.json
x-rate-limit:
  requests: 100
  window_seconds: 60
  scope: api_key
  headers:
  - Retry-After
  - X-RateLimit-Limit
  - X-RateLimit-Remaining
  - X-RateLimit-Reset
  headers_on: 429 only
  per_org:
  - operation: PATCH /voice/bridge/settings
    requests: 10
    window_seconds: 60
  - operation: PATCH /voice/bridge/numbers
    requests: 30
    window_seconds: 60
    counts: a voice_id, not null
  - operation: GET /voice/bridge/voices?set=all + GET /voice/bridge/voices/{voice_id}
    requests: 60
    window_seconds: 60
    counts: voices off the recommended list
  - operation: GET /voice/bridge/voices/{voice_id}/preview
    requests: 30
    window_seconds: 60
    counts: voices off the recommended list
x-error-codes: https://corebee.ai/api/v1/error-codes.json