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.
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
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