Webhook Events Reference

Payload shape for every event the platform emits. The names and samples on this page mirror what the dispatcher actually sends — generated from WEBHOOK_EVENT_TYPES in packages/shared/src/constants.ts and the dispatchTenantWebhook / buildWebhookJobs call sites. For the full catalog with one-liner descriptions, see Webhook Events.

Event Envelope

Every webhook delivery wraps the event in a standard envelope:

{
  "id": "evt_abc123",
  "type": "message.delivered",
  "created_at": "2026-03-08T12:00:00Z",
  "data": { "...": "event-specific payload" }
}

Field	Type	Description
`id`	string	Unique event ID (idempotency key)
`type`	string	Event type identifier (one of the values in this reference)
`created_at`	string	ISO 8601 timestamp
`data`	object	Event-specific payload
`truncated`	boolean (optional)	`true` only when the serialized envelope (`id` + `type` + `created_at` + `data`, JSON-encoded) exceeded 256 KB and `data` was replaced with a pointer-style envelope. Subscribers fetch the full resource via the API.

When truncated: true, data carries _truncated: true, _original_bytes, and a small set of identifier fields (id, message_id, conversation_id, contact_id, campaign_id, channel) so consumers can locate the resource.

Catalog Index

Every webhook event Orbit emits — 249 in total — grouped by surface. Each row links to its long-form payload section below; combined headings (e.g. campaign create / update / delete share one section) point to the first member.

Message Events

Event	Description
`message.created`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`message.sent`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`message.delivered`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`message.failed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`message.read`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`message.received`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`message.recipient_deactivated`	Carrier number deactivation sweep (R16FIX 2026-05-30) — fires once per deactivated MSISDN the nightly carrier-feed sweep flips to DNC.

Contact Events

Event	Description
`contact.created`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`contact.updated`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`contact.deleted`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`contact.trait_changed`	Computed-trait value transition for a single contact (DECISION — CDPAAS_REAL_TIME_TRAIT_RECOMPUTE_2026_05_28).
`contact.bulk_imported`	Fired once per bulk CSV import after all rows are processed.
`contact.merged`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`contact.opted_out`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`contact.opted_in`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`contact.recertification_due`	Reassigned Number Database (RMD) annual recertification due.
`contact.phone_changed`	WhatsApp customer-number-change recertification.
`contact.segment_changed`	Predictive-scoring events (migration 077).
`contact.entered_segment`	CDPAAS — SEGMENT_MEMBERSHIP_CHANGE_WEBHOOK (2026-05-31).
`contact.exited_segment`	Inverse of `contact.entered_segment`.

Campaign Events

Event	Description
`campaign.started`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`campaign.completed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`campaign.paused`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`campaign.resumed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`campaign.cancelled`	Fired by `cancelCampaign` when an operator cancels a running, paused, or scheduled campaign (terminal status `cancelled`).
`campaign.drip_step.sent`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`campaign.drip_step.completed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`campaign.drip.completed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`campaign.created`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`campaign.updated`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`campaign.deleted`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.

Voice Events

Event	Description
`call.initiated`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`call.answered`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`call.completed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`call.failed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`call.transferred`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`call.dtmf_sent`	Mid-call DTMF inject (B-237).
`call.recording.paused`	Mid-call recording pause (B-242).
`call.recording.resumed`	Mid-call recording resume (B-242).
`call.secure_payment.started`	Agent-assisted secure payment (masked-DTMF card capture, PCI Pal / Sycurio-class).
`call.secure_payment.completed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`call.secure_payment.cancelled`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`call.hit_voicemail`	Outbound call hit a voicemail or screened call (Jambonz AMD result: `machine`, `machine_beep_detected`, `fax`, `ios_call_screening`, or `ios_live_voicemail`).
`call.disclosure.omitted`	A call routed through a queue with mandated disclosure phrases ended without every required phrase being read.
`call.ringing`	Inbound INVITE seen at the SIP edge but call not yet answered.
`conference.created`	Conference lifecycle events (audit #BUG-R65).
`conference.participant_joined`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`conference.participant_left`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`conference.ended`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`recording.started`	Recording lifecycle events (audit #BUG-R65).
`recording.completed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`recording.failed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`recording.qc_failed`	Post-finalize QC failure (RTC-PaaS competitor-parity gap, 2026-05-29).
`voicemail.received`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`voicemail.transcript_updated`	Late-arriving transcript: fires when a voicemail’s transcript was NULL at receipt (Deepgram inline failure) and a subsequent retry recovered it.
`call.transcript_ready`	Telephony-aware CDP — CDP-016 parity wedge (2026-05-29).
`call.recording.ready`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`call.transcription.ready`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`call.synthesis.ready`	AI summary / action-items / sentiment extracted from the transcript (opt-in).
`call.synthesized`	Phase 4.4 — Post-call synthesis pipeline (scheduler-driven).
`recording.retention_deleted`	Fired ahead of a retention-driven GCS purge so tenants can mirror the recording/attachment to their own archive before it is deleted.
`recording.chapters.ready`	RTC-PaaS auto-chaptering (2026-05-28).
`recording.redaction_vault.ready`	Compliance recording vault (2026-06-10).
`voice_eval.run_started`	Voice eval regression suite (migration 282, 2026-05-22).
`voice_eval.run_completed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`voice_eval.regression_detected`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.

Agent Events

Event	Description
`agent.conversation.started`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`agent.conversation.ended`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`agent.created`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`agent.updated`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`agent.deleted`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`agent.deployed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`agent.state.changed`	CCaaS contact-center agent presence-state transition (2026-05-31).
`agent.handoff.requested`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`agent.handoff_occurred`	Fired when a conversation is handed to another specialist agent — both autonomous `transfer_to_agent` delegations and operator-initiated inbox-macro handoffs (`source_agent_id` is `operator_macro` for the latter).
`agent.response`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`agent.calendar_event.created`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`agent.dnc.marked`	AIaaS-P0-BUG fix (2026-05-30): fired by `POST /agents/dnc` when an AI voice / text agent invokes the `mark_dnc` MCP tool and the platform persists the suppression to `suppression_list` (+ `dnc_list` mirror for voice/S…
`agent.batch.completed`	Fired when an asynchronous agent batch inference job finishes and its results are ready to fetch.

Flow Events

Event	Description
`flow.execution.started`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`flow.execution.completed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`flow.created`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`flow.updated`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`flow.deleted`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`flow.published`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`flow.executed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`flow.execution.failed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.

Verification Events

Event	Description
`verification.sent`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`verification.approved`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`verification.failed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`verification.fraud_blocked`	Pre-send Fraud Guard refusal (`VerifyService.sendVerification`, fraud verdict `action === "block"`).
`verification.checked`	Fired by `VerifyService.checkVerification` on EVERY persisted check attempt — the terminal outcomes (`approved` / `failed` / `expired`) and the non-terminal `pending` outcome (wrong code but attempts remaining).
`verification.fallback_triggered`	Fired by `VerifyService.advanceFallbackChannel` (invoked by the `scheduler-verify-fallback` worker via `/internal/verify/fallback-advance`) each time the async fallback engine successfully fires a new channel.
`verification.fallback_exhausted`	Fired when the async fallback engine has tried every channel in the fallbackConfig.channels array without obtaining a `verified` status.

Number / Porting Events

Event	Description
`number.purchased`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`number.released`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`number.released_compliance_timeout`	Number auto-released because its compliance deadline elapsed (audit #COMPLIANCE-DEADLINE-2026-05-12).
`number.ported`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`number.inventory.low`	Low DID inventory alert (NaaS gap, anchor: PROTOCOL — NAAS_TN_LOW_STOCK_ALERT_2026_05_31).
`number.dormant`	Per-DID dormancy alert — fired when an owned number has had no inbound or outbound calls or SMS for the configured dormancy window, so integrations can release idle numbers and trim spend.
`number.health.degraded`	Per-DID deliverability health-degradation alert — fired when a number’s reputation got materially worse between two daily poller passes, so integrations can throttle a campaign or rotate the DID before the carriers ta…
`number.updated`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`porting.request.cancelled`	Number porting customer-cancellation event.
`porting.request.manual_review_required`	Port-IN fell back into manual-review mode (GAP2_NaaS_115, 2026-05-29).
`porting.request.loa_signed`	Port-IN LOA signed in-platform (cpaasparity2-porting-loa-workflow, 2026-05-29).
`porting.request.supplement_submitted`	Port-IN LOA/CSR supplement amendment submitted to the carrier.
`number.port_out.requested`	Number port-OUT lifecycle events (NaaS-005 capability-gap fix, 2026-05-29).
`number.port_out.cancelled`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.

Conversation Events

Event	Description
`conversation.created`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`conversation.disposed`	Fired by the auto-disposition service when a conversation is automatically closed/resolved by an AI or rule-based disposition engine.
`conversation.scored`	Fired by the QM-scoring service when a conversation receives a quality-management score.
`conversation.csat_detractor`	CSPaaS LOW_CSAT_AUTOMATION_HOOK_2026_05_30 — fired when a customer-facing CSAT (1..5, < 3) or NPS (0..10, 0..6) submission lands and qualifies as a detractor.
`conversation.synthesized`	AIaaS post-chat synthesis (2026-05-31) — Intercom Fin / Sierra parity.
`conversation.deflected`	CSPaaS Intercom Fin / Zendesk parity gap (2026-05-30) — CRM/CDP needs to distinguish AI-resolved volume from human-resolved volume.
`conversation.ai_review_needed`	Fired when a conversation that was resolved by AI — rather than handed to a human agent — comes back with a low CSAT score (below your configured threshold, default 3 of 5), flagging it for a human to review.
`conversation.started`	CONVERSATION_STARTED — the deliverable new-conversation webhook, fired on the inbound/handoff pipeline’s fresh-INSERT branch the moment a brand-new conversation opens.
`conversation.closed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.

Compliance Events

Event	Description
`compliance.10dlc.campaign.suspended`	A2P 10DLC campaign was suspended by TCR (The Campaign Registry) or a downstream MNO.

List / Segment Events

Event	Description
`list.created`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`list.updated`	A static contact list changed — either its metadata (renamed / description edited) OR its membership (a contact added or removed).
`list.deleted`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`segment.created`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`segment.deleted`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.

Webhook Endpoint Events

Event	Description
`webhook_endpoint.created`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`webhook_endpoint.updated`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`webhook_endpoint.deleted`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.

Billing Events

Event	Description
`subscription.updated`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`balance.topped_up`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`credits.purchased`	Use BALANCE_TOPPED_UP instead Deprecated.
`balance.low`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`credits.low`	Use BALANCE_LOW instead Deprecated.
`invoice.created`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`payment.failed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.

Commerce Events

Event	Description
`commerce.payment_request.status_changed`	The channel-agnostic hosted pay-by-link (`PaymentRequest`) that anchors every in-thread checkout advanced to a new lifecycle status (viewed / paid / expired / cancelled).

Channel Failover Events

Event	Description
`channel.failover`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.

Push Events

Event	Description
`push.delivered`	Push notification SDK ack events.
`push.opened`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.

Number Masking (Proxy) Events

Event	Description
`proxy.session.created`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`proxy.session.closed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`proxy.message.forwarded`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.

WhatsApp Events

Event	Description
`whatsapp.account.update`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.account.banned`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.account.restricted`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.phone.quality_update`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.phone.name_update`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.capability.update`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.security.alert`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.flow.status_change`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.template.submitted`	Fired the moment an operator authors a WhatsApp message template and it is submitted to Meta for review (`createTemplate`) — or instantiated from Meta’s instantly-approved Template Library (`createFromLibrary`).
`whatsapp.template.approved`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.template.rejected`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.template.quality_update`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.template.auto_paused`	Fired when a template is automatically paused locally because Meta reported a RED quality score and the operator opted that template into quality-degradation auto-pause.
`whatsapp.template.category_update`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.template.components_update`	Meta auto-edits a template’s components for compliance (e.g. inserts the standard opt-out hint into a MARKETING body).
`whatsapp.quality.changed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.call.received`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.call.connected`	WhatsApp Business Calling lifecycle events (Phase 2 — 2026-05-09).
`whatsapp.call.accepted`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.call.terminated`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.call.permission_granted`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.call.permission_revoked`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`whatsapp.account.alert`	Meta-issued operational alert about the WABA (e.g. policy violation, pricing change effective date, payment method failed).
`whatsapp.account.review_update`	WABA went through a Meta-side review that updated its compliance status (e.g. moved to RESTRICTED / FLAGGED).
`whatsapp.business.status_update`	Business profile status changed at Meta (verification badge, official business account flag, business status).
`whatsapp.user.preferences`	User-level marketing preference signal.
`whatsapp.data.export_request`	GDPR Article 15 (data subject access request) — user invoked “Request my data” inside the conversation.
`whatsapp.data.delete_request`	GDPR Article 17 (right to erasure) — user invoked “Delete my data”.
`whatsapp.account.settings_update`	WABA-level settings changed (commerce/profile/etc.).
`whatsapp.automatic_events`	Meta’s auto-detected business events (cart abandoned, etc.).
`whatsapp.group.lifecycle_update`	WA Group lifecycle (created/deleted).
`whatsapp.group.participants_update`	WA Group participants joined/left.
`whatsapp.group.settings_update`	WA Group renamed/description changed.
`whatsapp.group.status_update`	WA Group activated/archived.
`whatsapp.history`	Initial-connection backfill of historical messages.
`whatsapp.partner_solutions`	Partner integration events.
`whatsapp.payment_configuration_update`	Payment setup state changed (WA Pay).
`whatsapp.smb.app_state_sync`	SMB app state sync events.
`whatsapp.smb.message_echoes`	Echoes of messages sent from the SMB app (hybrid setups).
`whatsapp.template.correct_category_detection`	Meta detected the template’s category was wrong vs. its actual intent.
`whatsapp.tracking_events`	Per-message tracking events (link clicks, etc.).
`whatsapp.order.received`	Conversational-commerce order capture.

Supervisor Events

Event	Description
`supervisor.takeover_requested`	Fired when a supervisor initiates a warm-handoff takeover of a live call.
`supervisor.takeover_failed`	Fired when a supervisor takeover attempt fails (e.g. Jambonz REST error during the leg-swap).
`supervisor.takeover_completed`	Fired when the supervisor successfully takes over the call and becomes the active party.
`supervisor.takeover_cancelled`	Fired when a takeover is cancelled (call ended before handoff completed, or supervisor explicitly aborted).

SIP Trunk Events

Event	Description
`sip_trunk.status_changed`	A customer SIP trunk’s registration state transitioned between `registered` and `unregistered`.

CDP Events

Event	Description
`cdp.event.ingested`	CDP inbound — fired after a Segment-shaped /cdp/track or /cdp/identify payload is verified, persisted to `tenant_.cdp_events`, and identity- resolved against `tenant_.contacts`.
`cdp.identity.resolved`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`cdp.tracking_plan.violation_spike`	CDP_TRACKING_PLAN_VIOLATION_SPIKE — proactive data-quality alert (CDPAAS, 2026-06-10).

Other

Event	Description
`email.opened`	Email engagement events (Resend webhook surface).
`email.clicked`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`short_link.click`	Tracked short-link click (SMS / WhatsApp click-tracking).
`video.recording.degraded`	PARITY-RTC-R1 (2026-05-29) — video room recording QC verdict.
`video.room.started`	GAP-RTC-R2 (2026-05-29) — video room + participant + recording lifecycle webhook fan-out.
`video.room.ended`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`video.participant.joined`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`video.participant.left`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`video.recording.completed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`video.recording.failed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`video.active_speakers.changed`	GAP-RTC-R3 (2026-05-31) — dominant/active-speaker change event.
`video.ingress.started`	GAP-RTC-R3 (2026-05-30) — ingress lifecycle webhooks.
`video.ingress.ended`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`video.ingress.failed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`video.recording.transcript_ready`	RTC-PaaS parity (2026-05-31) — async post-meeting transcription of a video room recording is complete.
`video.participant.qos`	RTC-PaaS parity (2026-06-12) — live per-participant QoS telemetry.
`video.caption.segment`	RTC-PaaS parity (2026-07-07) — live caption segment fired per completed caption line for real-time downstream consumption.
`video.participant.muted`	A moderator force-muted a participant’s audio or video track (`kind`).
`video.participant.unmuted`	A moderator cleared a participant’s force-mute on a track (`kind`).
`video.participant.kicked`	A moderator booted a participant from the live room (ephemeral — the identity can rejoin).
`video.participant.banned`	A moderator persistently barred a participant identity from rejoining the room.
`video.participant.unbanned`	A moderator lifted a persistent ban so the identity may rejoin the room.
`video.participant.role_changed`	A participant’s in-meeting role changed (`role`: attendee \| presenter \| moderator).
`video.participant.spotlighted`	A moderator spotlighted (pinned) a participant as the foregrounded track for everyone.
`video.room.spotlight_cleared`	A moderator cleared the room spotlight, returning to the base speaker/grid layout.
`video.participant.hand_raised`	A participant raised their hand (or a moderator raised it on their behalf).
`video.participant.hand_lowered`	A participant’s raised hand was lowered (self-lowered or cleared by a moderator).
`connectivity_sim.usage_warning`	Per-SIM data-usage warning — fired when a connectivity SIM’s cumulative usage crosses its configured warning threshold (but is still under the hard data limit), so integrations can notify the end user or top up the pl…
`connectivity_sim.limit_exceeded`	Per-SIM data-limit-exceeded alert — fired when a connectivity SIM’s cumulative usage reaches or passes its hard data limit and the SIM is suspended/throttled for quota, so integrations can react (top up, notify, re-pr…
`connectivity_sim.ordered`	Connectivity SIM ordered — fired when a new eSIM / IoT (M2M) SIM is provisioned against a catalog plan (POST /numbers/connectivity/sims), so integrations can mirror the new line into an asset inventory or kick off dow…
`connectivity_sim.activated`	Connectivity SIM activated — fired when a SIM transitions to `active` (POST /numbers/connectivity/sims/:iccid/activate), so integrations know the line can now carry data.
`connectivity_sim.suspended`	Connectivity SIM suspended — fired when a SIM transitions to `suspended` (POST /numbers/connectivity/sims/:iccid/suspend), so integrations can pause billing or alert the owner.
`connectivity_sim.resumed`	Connectivity SIM resumed — fired when a `suspended` SIM is returned to `active` (POST /numbers/connectivity/sims/:iccid/resume).
`connectivity_sim.terminated`	Connectivity SIM terminated — fired when a SIM is permanently terminated (POST /numbers/connectivity/sims/:iccid/terminate), a terminal lifecycle sink, so integrations can decommission the line.
`audit.log.created`	Continuous audit-log streaming to a customer SIEM (CSPaaS pillar gap act_mq5oa7po).
`ticket.deflected`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`ticket.automation_applied`	Fired when an operator-authored inbox automation rule matches a ticket lifecycle event (created / status changed / priority changed / idle) and applies its actions.
`wallboard.sla_warning`	Voice-queue wallboard SLA early-warning (CCaaS).
`wallboard.alarm_triggered`	Configurable per-rule voice-queue wallboard alarm fired (CCaaS SLA breach alerting, 2026-05-30 wave 2).
`wfm.adherence_breach`	WFM intraday adherence breach (CCaaS / WFM pillar, 2026-05-30).
`survey.csat.response_recorded`	Post-call IVR survey response recorded (CCaaS, 2026-05-30).
`survey.nps.response_recorded`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`survey.response.detractor`	CXaaS closed-loop survey feedback — a recipient-facing survey response (the `surveys` product: `apps/api/src/routes/public/survey-response.controller.ts`) landed at detractor level (NPS <= 6 of 10, CSAT <= 6 of 10).
`queue.call.queued`	CCaaS queue-routing lifecycle webhooks (Five9 / Genesys parity — `Interaction.Routed` / `Interaction.Abandoned`).
`queue.call.abandoned`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`queue.call.assigned`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`queue.alert_rule_fired`	CCaaS supervisor wallboard — user-configurable alert rule fired (acd_queue_alert_rules row with action=‘webhook’).
`integration.auth_failed`	Integration health events (Nango-managed CRM / helpdesk / automation connectors).
`integration.sync_failed`	Platform-defined webhook event. See source comment in `packages/shared/src/constants.ts` for context.
`account.fraud.alert`	Account-level fraud / security alert (CSPAAS-FRAUD-ALERT, 2026-06-09).
`subaccount.spend_cap.threshold`	Subaccount month-to-date spend crossed a cap threshold (CSPaaS reseller billing controls).
`slack.slash_command`	Slack slash-command received (Integrations — Slack).
`slack.event_received`	Slack Events API callback received (Integrations — Slack).
`slack.interactivity`	Slack interactivity payload received (Integrations — Slack).
`calendly.invitee.created`	Calendly invitee booked a meeting (Integrations — Calendly).
`calendly.invitee.canceled`	Calendly invitee canceled a booked meeting (Integrations — Calendly).
`calendly.invitee_no_show.created`	Calendly invitee marked as a no-show (Integrations — Calendly).
`calendly.routing_form_submission.created`	Calendly routing-form submission received (Integrations — Calendly).
`reverse_etl.sync.failed`	A tenant reverse-ETL (CDPaaS) sync run to a downstream warehouse destination failed (Integrations — Reverse-ETL).

Message Events

Every message lifecycle event (message.sent, message.delivered, message.failed, message.read, plus the submitted_no_receipt and expired transitions) carries a state_class field alongside status. It tags the transition as either "intermediate" (the status may still progress — e.g. submitted_no_receipt, where a later genuine delivered can land) or "terminal" (a final outcome such as delivered / failed / read), so per-message status_callback subscribers can distinguish the two without re-deriving the status taxonomy.Each lifecycle payload also carries is_terminal (boolean) — a convenience discriminator that is always equivalent to state_class === "terminal". Both derive from the same terminal-status allow-list and can never disagree, so high-volume senders can branch on a single truthy flag (if (dlr.is_terminal)) instead of string-comparing the enum. Like state_class, is_terminal is present only on lifecycle transitions (where status is defined). Engagement events (email.opened / email.clicked) are not lifecycle transitions and intentionally omit both state_class and is_terminal.

`message.created`

Fired when an outbound message is accepted and queued for delivery.

{
  "id": "evt_abc",
  "type": "message.created",
  "created_at": "2026-03-08T12:00:00Z",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "to": "+14155552671",
    "from": "+18005551234",
    "status": "queued",
    "created_at": "2026-03-08T12:00:00Z"
  }
}

`message.sent`

Fired when the message is handed off to the carrier / provider.

{
  "type": "message.sent",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "to": "+14155552671",
    "status": "sent",
    "state_class": "intermediate",
    "is_terminal": false,
    "external_id": "carrier-side-id"
  }
}

`message.delivered`

{
  "type": "message.delivered",
  "data": {
    "message_id": "msg_abc123",
    "status": "delivered",
    "state_class": "terminal",
    "is_terminal": true,
    "channel": "sms",
    "timestamp": "2026-03-08T12:00:03Z"
  }
}

`message.failed`

Terminal failure reported by the carrier (or a synthesised failure covering undelivered, rejected, expired, and submitted_no_receipt — all of which STATUS_TO_EVENT fans out on this event; branch on the payload’s status field to tell them apart).

{
  "type": "message.failed",
  "data": {
    "message_id": "msg_abc123",
    "status": "failed",
    "state_class": "terminal",
    "is_terminal": true,
    "channel": "sms",
    "timestamp": "2026-03-08T12:00:05Z",
    "error_code": "30003",
    "error_message": "Unreachable destination handset"
  }
}

error_code and error_message are optional — they appear only when the message carries a provider-supplied failure reason. They mirror the raw code and human-readable text the carrier / channel returned (for example a WhatsApp Cloud API errors[0].code / .title, or an SMS / email carrier failure), and are the same error_code / error_message values the REST message object and SDK expose. Both are strings. A message.failed payload for a message with no captured provider error omits both keys, so treat them as may-be-absent rather than null. Successful transitions (message.sent, message.delivered, message.read) clear any prior failure reason, so those events never carry these two fields. The expired and submitted_no_receipt transitions (also delivered via message.failed, below) follow the same rule.

`message.read`

{
  "type": "message.read",
  "data": {
    "message_id": "msg_abc123",
    "status": "read",
    "state_class": "terminal",
    "is_terminal": true,
    "channel": "whatsapp",
    "timestamp": "2026-03-08T12:00:10Z"
  }
}

`message.received`

Inbound message from a recipient.

{
  "type": "message.received",
  "data": {
    "message_id": "msg_inb_456",
    "channel": "sms",
    "from": "+14155552671",
    "to": "+18005551234",
    "body": "What is my order status?",
    "metadata": { "raw_provider_id": "..." }
  }
}

`expired` and `submitted_no_receipt` (delivered via `message.failed`)

These two terminal-non-success transitions do not dispatch dedicated message.expired / message.submitted_no_receipt webhook events. The dispatcher’s STATUS_TO_EVENT map (apps/api/src/routes/webhooks/dlr-common.ts) fans both out on message.failed, matching the per-status webhook table in the message status lifecycle reference. Subscribe to message.failed and branch on the payload’s status field to distinguish them. The MESSAGE_EXPIRED / MESSAGE_SUBMITTED_NO_RECEIPT constants in packages/shared/src/constants.ts are reserved for a future multi-event-per-status emitter and are not emitted today. expired — a delivery receipt arrived past the late-arrival window (DEVOTEL_DLR_LATE_ARRIVAL_MAX_AGE_DAYS) and the message can no longer be reconciled. state_class is terminal.

{
  "type": "message.failed",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "status": "expired",
    "state_class": "terminal",
    "is_terminal": true,
    "timestamp": "2026-03-08T12:05:00Z"
  }
}

submitted_no_receipt — the provider accepted the submission (SMPP submit_sm ACK, or a Meta DM hand-off) but no delivery receipt returned within the grace window. state_class is intermediate — a later genuine delivered can still land, so do not treat this as a final outcome.

{
  "type": "message.failed",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "status": "submitted_no_receipt",
    "state_class": "intermediate",
    "is_terminal": false,
    "timestamp": "2026-03-08T12:05:00Z"
  }
}

`message.recipient_deactivated`

Fired by the nightly carrier number-deactivation sweep once per deactivated MSISDN it flips to DNC (closing the TCPA-liability gap from texting recycled numbers). This is not tied to a single message, so it carries no message_id; instead it documents the deactivated number and its provenance. carrier may be null when the feed does not report it; source defaults to telnyx_feed.

{
  "type": "message.recipient_deactivated",
  "data": {
    "phone": "+14155552671",
    "deactivated_at": "2026-03-07T00:00:00Z",
    "carrier": "Verizon Wireless",
    "source": "telnyx_feed",
    "observed_at": "2026-03-08T03:00:00Z"
  }
}

Contact Events

`contact.created`

{ "type": "contact.created", "data": { "contact_id": "con_abc123" } }

`contact.updated`

{ "type": "contact.updated", "data": { "contact_id": "con_abc123" } }

`contact.deleted`

{ "type": "contact.deleted", "data": { "contact_id": "con_abc123" } }

`contact.merged`

{ "type": "contact.merged", "data": { "contact_id": "con_abc123" } }

`contact.bulk_imported`

Fired once per bulk import batch (CSV upload or POST /v1/contacts/bulk), not once per row. The payload summarises the whole batch.

This event is emitted whenever a batch changes at least one contact — that is, when any of imported, updated, or failed is nonzero. Update-only batches run in upsert mode, where every row matched an existing contact (imported: 0, failed: 0, updated > 0), do emit this event, so you can drive downstream sync directly from contact.bulk_imported. Only a no-op batch where all three counts are 0 does not emit.

{
  "id": "evt_abc",
  "type": "contact.bulk_imported",
  "created_at": "2026-03-08T12:00:00Z",
  "data": {
    "imported": 480,
    "updated": 12,
    "failed": 8,
    "total": 488,
    "import_batch_id": "imb_abc123"
  }
}

Field	Type	Description
`imported`	integer	New contact rows created on this batch
`updated`	integer	Existing contact rows merged on this batch (upsert toggle on)
`failed`	integer	Rows rejected by validation / dedup / DB constraint
`total`	integer	`imported + failed` (does not include `updated`)
`import_batch_id`	string \| null	Stable identifier for this batch — present when the API was able to persist the import-jobs row; `null` only on legacy in-line imports without a job row

Delivery semantics: at-least-once. This event rides the standard webhook delivery queue. On a transient receiver error (5xx, timeout) Orbit re-queues the delivery on an exponential backoff retry schedule — up to 9 retries with a 30-second base delay that doubles with each attempt (capping at ~4.3 hours total), each delay carrying +0–20% jitter (up to 20% longer than the nominal interval, never shorter), then moves the delivery to the dead-letter queue (DLQ). See the Retry Schedule for the full policy. Because of these retries the same contact.bulk_imported payload can be delivered more than once. Orbit does not guarantee exactly-once delivery on any webhook.Your consumer must be idempotent. Recommended dedupe key, in order of preference:

Envelope id — the top-level event id is unique per delivery attempt’s logical event and is the canonical idempotency key for every Orbit webhook (id is stable across retries of the same event). Persist seen id values long enough to cover the full retry window — the active schedule is 10 attempts total on an exponential backoff starting at 30 seconds and doubling each retry (30s, 60s, 120s, …, plus jitter), spanning ~4.3h end-to-end before a delivery reaches the DLQ — plus the dead-letter replay window. A retention of at least 3 days comfortably covers both.
data.import_batch_id — when non-null, import_batch_id is the natural key for the underlying batch. If you write summary counters into your own DB, key them on import_batch_id so a replay does not double-add the totals.

If neither key is available (import_batch_id: null and a malformed envelope), treat the delivery as a no-op observability signal and fetch authoritative state via GET /v1/contacts/import-jobs.

`contact.opted_in` / `contact.opted_out`

Fired when a recipient sends a START / STOP keyword on a registered channel.

{
  "type": "contact.opted_out",
  "data": {
    "channel": "sms",
    "phone": "+14155552671",
    "keyword": "STOP",
    "timestamp": "2026-03-08T12:05:00Z"
  }
}

`contact.recertification_due`

FCC RMD annual consent recertification window opened on a contact.

{
  "type": "contact.recertification_due",
  "data": {
    "contact_id": "con_abc123",
    "consent_id": "consent_xyz",
    "channel": "sms",
    "granted_at": "2025-05-09T00:00:00Z",
    "age_days": 365,
    "phone_number": "+14155552671",
    "email": null,
    "timestamp": "2026-05-09T00:00:00Z"
  }
}

`contact.phone_changed`

Fired when WhatsApp (Meta) notifies Orbit that a customer moved to a new phone number. Orbit reconciles the matching contacts onto the new number and re-certifies their standing consent, then emits this event with the bulk outcome. This is a different contract from contact.recertification_due: it reports a completed re-certification across one or more contacts, not a single contact whose annual consent window just opened.

{
  "type": "contact.phone_changed",
  "data": {
    "contact_ids": ["con_abc123", "con_def456"],
    "previous_phone": "+14155552671",
    "new_phone": "+14155559900",
    "reason": "customer_changed_number",
    "consent_recertified_count": 2,
    "source": "whatsapp_system_event",
    "source_message_id": "wamid.HBgL...",
    "occurred_at": "2026-05-09T00:00:00Z"
  }
}

source_message_id is the originating WhatsApp message id and may be null. consent_recertified_count counts the consent records Orbit re-certified during the reconciliation and is always >= 1 for a delivered event.

`contact.segment_changed`

Predictive scorer flipped a contact’s segment label (e.g. champion → at_risk, passive → engaged). Useful for triggering re-engagement plays from a CRM.

{
  "type": "contact.segment_changed",
  "data": {
    "contact_id": "con_abc123",
    "previous_label": "champion",
    "new_label": "at_risk",
    "churn_risk": 0.71,
    "intent_score": 0.32,
    "propensity_score": 0.18,
    "ltv_estimate_cents": 12400,
    "signals": ["sms_open_drop", "click_drop"],
    "computed_at": "2026-03-08T12:00:00Z"
  }
}

Campaign Events

`campaign.created` / `campaign.updated` / `campaign.deleted`

{ "type": "campaign.created", "data": { "campaign_id": "camp_abc123" } }

`campaign.started`

{
  "type": "campaign.started",
  "data": { "campaign_id": "camp_abc123", "status": "running" }
}

`campaign.completed`

Fires once when a campaign reaches a terminal state. This is the terminal event for both success and failure paths — a campaign that never sends (its audience couldn’t be resolved, resolved to zero contacts, or had no addressable contacts) still emits campaign.completed, not a separate failure event. Branch on status, not on the presence of the event. status is one of:

completed — the campaign finished; every recipient was attempted.
partially_failed — the campaign finished, but some sends failed.
failed — the campaign ended without a successful send.

On failure and no-op paths the payload also carries completion_reason, one of:

audience_resolution_failed — the audience query errored before any send.
no_addressable_contacts — no contact had the address the channel needs (for example, an SMS campaign whose contacts have no phone number). status is failed.
no_recipients — the audience resolved to zero contacts. status is completed (nothing failed; there was simply nothing to send).

Count fields (sent_count, delivered_count, failed_count) are present when the campaign got far enough to attempt delivery. Success:

{
  "type": "campaign.completed",
  "data": {
    "campaign_id": "camp_abc123",
    "status": "completed",
    "sent_count": 480,
    "delivered_count": 472,
    "failed_count": 8,
    "completed_at": "2026-03-08T12:00:00Z"
  }
}

Terminal failure (audience could not be resolved):

{
  "type": "campaign.completed",
  "data": {
    "campaign_id": "camp_abc123",
    "status": "failed",
    "completion_reason": "audience_resolution_failed",
    "completed_at": "2026-03-08T12:00:00Z"
  }
}

`campaign.paused` / `campaign.resumed`

{ "type": "campaign.paused", "data": { "campaign_id": "camp_abc123" } }

`campaign.drip_step.completed`

Single drip step finished sending to its slice.

{
  "type": "campaign.drip_step.completed",
  "data": {
    "campaign_id": "camp_abc123",
    "step_index": 2,
    "sent": 480,
    "failed": 12
  }
}

`campaign.drip.completed`

Entire drip campaign finished its full schedule.

{
  "type": "campaign.drip.completed",
  "data": {
    "campaign_id": "camp_abc123",
    "status": "completed",
    "summary": {
      "total": 2400,
      "active": 0,
      "completed": 2340,
      "dropped": 0,
      "failed": 60
    }
  }
}

Voice Events

`call.initiated`

{ "type": "call.initiated", "data": { "call_id": "call_abc123" } }

When the call is bridged through Jambonz, the payload also carries provider and direction context:

{
  "type": "call.initiated",
  "data": {
    "call_id": "call_abc123",
    "provider": "jambonz",
    "provider_call_sid": "CA-…",
    "direction": "inbound",
    "from": "+14155552671",
    "to": "+18005551234",
    "status": "ringing",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

`call.answered`

{
  "type": "call.answered",
  "data": {
    "call_id": "call_abc123",
    "provider": "jambonz",
    "provider_call_sid": "CA-…",
    "direction": "inbound",
    "from": "+14155552671",
    "to": "+18005551234",
    "status": "in-progress",
    "timestamp": "2026-03-08T12:00:08Z"
  }
}

`call.completed`

{
  "type": "call.completed",
  "data": {
    "call_id": "call_abc123",
    "provider": "jambonz",
    "provider_call_sid": "CA-…",
    "direction": "inbound",
    "from": "+14155552671",
    "to": "+18005551234",
    "status": "completed",
    "duration_seconds": 142,
    "hangup_reason": "normal_clearing",
    "sip_response_code": 200,
    "sip_reason": "OK",
    "timestamp": "2026-03-08T12:02:22Z"
  }
}

`call.failed`

{
  "type": "call.failed",
  "data": {
    "call_id": "call_abc123",
    "provider": "jambonz",
    "provider_call_sid": "CA-…",
    "direction": "outbound",
    "from": "+18005551234",
    "to": "+14155559999",
    "status": "no-answer",
    "duration_seconds": 0,
    "hangup_reason": "no_user_response",
    "sip_response_code": 480,
    "sip_reason": "Temporarily Unavailable",
    "timestamp": "2026-03-08T12:00:30Z"
  }
}

`call.transferred`

data.transfer_type is one of blind, warm, or queue.

{
  "type": "call.transferred",
  "data": {
    "call_id": "call_abc123",
    "transferred_to": "+14155558888",
    "transfer_type": "blind"
  }
}

`call.dtmf_sent`

Mid-call DTMF inject through the API.

{
  "type": "call.dtmf_sent",
  "data": {
    "call_id": "call_abc123",
    "digits": "1234",
    "duration_ms": 100,
    "gap_ms": 80,
    "timestamp": "2026-03-08T12:01:30Z"
  }
}

`call.recording.paused` / `call.recording.resumed`

SIPREC fork toggled mid-call.

{
  "type": "call.recording.paused",
  "data": {
    "call_id": "call_abc123",
    "recording": false,
    "timestamp": "2026-03-08T12:01:00Z"
  }
}

`call.secure_payment.started` / `call.secure_payment.completed` / `call.secure_payment.cancelled`

Agent-assisted secure payment (masked-DTMF card capture, PCI Pal / Sycurio-class). Emitted by VoiceService.startSecurePaymentSession / finalizeSecurePaymentSession. While a session is started the SIPREC recording is paused and the caller’s keypad DTMF is masked from the agent (PCI-DSS agent descoping). The completed payload carries only the masked summary (card_last4, card_brand) — never the PAN. call.secure_payment.started:

{
  "type": "call.secure_payment.started",
  "data": {
    "call_id": "call_abc123",
    "session_id": "secpay_abc123",
    "fields": ["pan", "expiry", "cvv"],
    "started_at": "2026-03-08T12:03:00Z",
    "timestamp": "2026-03-08T12:03:00Z"
  }
}

call.secure_payment.completed — masked summary only:

{
  "type": "call.secure_payment.completed",
  "data": {
    "call_id": "call_abc123",
    "session_id": "secpay_abc123",
    "status": "completed",
    "card_last4": "4242",
    "card_brand": "visa",
    "timestamp": "2026-03-08T12:04:10Z"
  }
}

call.secure_payment.cancelled:

{
  "type": "call.secure_payment.cancelled",
  "data": {
    "call_id": "call_abc123",
    "session_id": "secpay_abc123",
    "status": "cancelled",
    "card_last4": null,
    "card_brand": null,
    "timestamp": "2026-03-08T12:03:45Z"
  }
}

After a session ends (completed or cancelled) the SIPREC recording resumes automatically — listen for call.recording.resumed.

`call.recording.ready`

{
  "type": "call.recording.ready",
  "data": {
    "call_id": "call_abc123",
    "recording_url": "gs://devotel-recordings/...",
    "duration_seconds": 142,
    "timestamp": "2026-03-08T12:06:00Z"
  }
}

`call.transcription.ready`

{
  "type": "call.transcription.ready",
  "data": {
    "call_id": "call_abc123",
    "transcript_length": 4820,
    "timestamp": "2026-03-08T12:06:30Z"
  }
}

`call.synthesis.ready` (legacy inline pipeline)

{
  "type": "call.synthesis.ready",
  "data": {
    "call_id": "call_abc123",
    "summary": "Customer asked about order ORD-12345…",
    "action_items": ["Send tracking link"],
    "sentiment": "neutral",
    "topics": ["order_status"],
    "timestamp": "2026-03-08T12:07:00Z"
  }
}

`call.synthesized` (post-call synthesis pipeline)

Richer payload from the async synthesis scheduler. Gated on tenant opt-in.

{
  "type": "call.synthesized",
  "data": {
    "call_id": "call_abc123",
    "direction": "inbound",
    "from": "+14155552671",
    "to": "+18005551234",
    "duration_seconds": 142,
    "ended_at": "2026-03-08T12:02:22Z",
    "synthesis": {
      "summary": "...",
      "sentiment": "neutral",
      "key_points": ["..."],
      "follow_up_actions": ["..."],
      "facts_learned": ["..."],
      "customer_intent": "order_status",
      "resolution": "resolved"
    },
    "synthesised_at": "2026-03-08T12:08:00Z"
  }
}

`call.ringing`

Fires when an inbound call is detected by the SIP edge but before it is answered. Useful for “live caller is dialing in” UI updates without waiting for the post-answer call.answered event.

{
  "type": "call.ringing",
  "data": {
    "call_id": "call_abc123",
    "provider": "jambonz",
    "provider_call_sid": "CA-…",
    "direction": "inbound",
    "from": "+14155552671",
    "to": "+18005551234",
    "status": "ringing",
    "timestamp": "2026-03-08T12:00:01Z"
  }
}

Trigger condition: carrier sends INVITE to the SIP edge. Retry behaviour: standard webhook retry (exponential backoff, 10 attempts over ~4.3 hours, with +0–20% jitter applied to delays — see Retry Schedule). Idempotent — call.ringing fires at most once per call. The emit is deduplicated by provider_call_sid for one hour, so a call routed across multiple ring-group legs still produces a single ringing callback. Note (current implementation): for inbound calls, call.initiated also fires with status: "ringing", so ringing is covered even if you only listen for call.initiated. The standalone call.ringing event uses the same subscription rules as every other event — list call.ringing in your endpoint’s events array, or use "events": ["*"]. If call.ringing is missing from your delivery, confirm your endpoint subscribes to it (or *), or fall back to listening for call.initiated with status: "ringing".

Conference Events

Conference lifecycle events fire from the conference service in apps/api/src/routes/voice/. The events ride the same delivery + retry semantics as call events.

`conference.created`

Fires when POST /api/v1/voice/conferences succeeds.

{
  "type": "conference.created",
  "data": {
    "conference_id": "conf_abc123",
    "name": "Q1 Planning Call",
    "max_participants": 25,
    "record": true,
    "created_by_user_id": "usr_xxx",
    "participants_requested": 3,
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

`conference.participant_joined`

Fires when a new participant successfully joins (after 200 OK to the SIP INVITE for that leg).

{
  "type": "conference.participant_joined",
  "data": {
    "conference_id": "conf_abc123",
    "participant_id": "cpart_def456",
    "call_sid": "call_xyz789",
    "phone_number": "+14155552671",
    "role": "participant",
    "timestamp": "2026-03-08T12:01:14Z",
    "joined_at": "2026-03-08T12:01:14Z"
  }
}

`conference.participant_left`

Fires when a participant disconnects — either via DELETE API call, BYE from the carrier, or the conference moderator’s end-conference action.

{
  "type": "conference.participant_left",
  "data": {
    "conference_id": "conf_abc123",
    "participant_id": "cpart_def456",
    "call_sid": "call_xyz789",
    "phone_number": "+14155552671",
    "role": "participant",
    "duration_seconds": 312,
    "left_at": "2026-03-08T12:06:26Z",
    "hangup_reason": "Normal Call Clearing",
    "sip_response_code": 200,
    "timestamp": "2026-03-08T12:06:26Z"
  }
}

hangup_reason is the free-text disconnect cause reported by the carrier/softswitch (for example Normal Call Clearing, caller hangup, or RTP timeout) — it is not a fixed enum, so match on substrings rather than exact values. sip_response_code is the numeric SIP status for the leg (e.g. 200), or null when none was received.

`conference.ended`

Fires when the conference’s active participant count drops to zero, or moderator hits end-conference. Always the LAST event for a conference id.

{
  "type": "conference.ended",
  "data": {
    "conference_id": "conf_abc123",
    "ended_at": "2026-03-08T12:30:40Z",
    "duration_seconds": 1840,
    "participant_count": 7,
    "end_reason": "all_legs_terminated",
    "final_status": "completed",
    "timestamp": "2026-03-08T12:30:40Z"
  }
}

end_reason values: all_legs_terminated (the active participant count dropped to zero), manual_end (a moderator or operator ended the conference), timeout (the max-duration TTL backstop closed the room). final_status carries the conference’s terminal status (completed, failed). ended_at is the UTC timestamp the conference closed.

Recording Events

`recording.started`

Fires when POST /api/v1/voice/calls/{id}/recording/start (or the per-call record:true flag) starts a fresh recording.

{
  "type": "recording.started",
  "data": {
    "recording_id": "rec_abc123",
    "call_id": "call_abc123",
    "classification": "call",
    "started_at": "2026-03-08T12:00:08Z",
    "timestamp": "2026-03-08T12:00:08Z"
  }
}

classification tells you which surface produced the recording so you can route the event without a follow-up API call. It is one of call, conference, ai_agent, browser_softphone, or video_room. Conference recordings carry conference_id in place of call_id.

`recording.completed`

Alias for call.recording.ready (same payload + same recording_url). Documented separately because the call-id may not be available for conference recordings — those carry conference_id instead.

{
  "type": "recording.completed",
  "data": {
    "recording_id": "rec_abc123",
    "call_id": "call_abc123",
    "classification": "call",
    "duration_seconds": 142,
    "recording_url": "https://storage.devotel.io/recordings/rec_abc123.mp3",
    "completed_at": "2026-03-08T12:06:00Z",
    "timestamp": "2026-03-08T12:06:00Z"
  }
}

`recording.failed`

Fires when an upstream recording attempt fails (storage write failure, codec mismatch, AMD aborted the recording before any audio was captured).

{
  "type": "recording.failed",
  "data": {
    "recording_id": "rec_abc123",
    "call_id": "call_abc123",
    "classification": "call",
    "reason": "storage_write_failed",
    "failed_at": "2026-03-08T12:06:02Z",
    "timestamp": "2026-03-08T12:06:02Z"
  }
}

reason is the machine-readable failure cause — read it for the reason this recording failed. failed_at is when the failure occurred (it may predate timestamp, which is when the webhook was emitted). classification tells you which surface produced the recording (call, conference, ai_agent, browser_softphone, or video_room); conference recordings carry conference_id in place of call_id.

`voicemail.received`

{
  "type": "voicemail.received",
  "data": {
    "voicemail_id": "vm_abc123",
    "call_id": "call_abc123",
    "from": "+14155552671",
    "transcript": "Hi, please call me back at noon — I had a question about…",
    "timestamp": "2026-03-08T12:05:00Z"
  }
}

`voicemail.transcript_updated`

Fires when an originally-missing voicemail transcript is recovered by the retry pipeline.

{
  "type": "voicemail.transcript_updated",
  "data": {
    "voicemail_id": "vm_abc123",
    "transcript": "Recovered transcript text…"
  }
}

`recording.retention_deleted`

Fires 24h before a retention-driven GCS purge so tenants can mirror the asset to their own archive. Payload carries a signed download URL valid until purge_scheduled_at.

{
  "type": "recording.retention_deleted",
  "data": {
    "source": "call",
    "source_id": "call_abc123",
    "channel": "voice",
    "created_at": "2025-05-08T00:00:00Z",
    "gcs_uri": "gs://...",
    "download_url": "https://storage.googleapis.com/...?X-Goog-Signature=...",
    "download_url_expires_at": "2026-05-10T00:00:00Z",
    "purge_scheduled_at": "2026-05-10T00:00:00Z",
    "retention_policy": {
      "voice_days": 365,
      "sms_days": 365,
      "email_days": 365,
      "whatsapp_days": 365,
      "rcs_days": 365,
      "viber_days": 365,
      "apply_hard_delete": true
    },
    "timestamp": "2026-05-09T00:00:00Z"
  }
}

Agent Events

`agent.created` / `agent.updated` / `agent.deleted` / `agent.deployed`

{
  "type": "agent.created",
  "data": {
    "agent_id": "agt_abc123",
    "name": "Support Bot",
    "type": "voice"
  }
}

`agent.conversation.started`

{
  "type": "agent.conversation.started",
  "data": {
    "conversation_id": "conv_001",
    "agent_id": "agt_abc123",
    "model": "claude-sonnet-4-6",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

`agent.conversation.ended`

{
  "type": "agent.conversation.ended",
  "data": {
    "conversation_id": "conv_001",
    "agent_id": "agt_abc123",
    "reason": "Escalated to human agent",
    "end_status": "escalated",
    "timestamp": "2026-03-08T12:15:00Z"
  }
}

`agent.handoff.requested`

Agent escalated to a human operator.

{
  "type": "agent.handoff.requested",
  "data": {
    "conversation_id": "conv_001",
    "agent_id": "agt_abc123",
    "reason": "Customer requested human agent",
    "status": "escalated"
  }
}

`agent.handoff_occurred`

A conversation was handed to another specialist agent — either an autonomous transfer_to_agent delegation or an operator-initiated handoff run from an inbox macro. For macro-driven handoffs source_agent_id is operator_macro.

{
  "type": "agent.handoff_occurred",
  "data": {
    "handoff_id": "ho_001",
    "source_agent_id": "agt_general",
    "target_agent_id": "agt_billing",
    "conversation_id": "conv_001",
    "reason": "Billing question",
    "summary": "User asked about invoice INV-2026-…"
  }
}

`agent.calendar_event.created`

Fires from the agent’s create_calendar_event MCP tool.

{
  "type": "agent.calendar_event.created",
  "data": {
    "event_id": "cal_evt_001",
    "title": "Meeting with Jane Doe",
    "description": "Discuss enterprise plan",
    "start_time": "2026-03-09T10:00:00Z",
    "end_time": "2026-03-09T10:30:00Z",
    "attendee_email": "jane@example.com",
    "conversation_id": "conv_001"
  }
}

Flow Events

`flow.created` / `flow.updated` / `flow.published` / `flow.deleted`

{ "type": "flow.created", "data": { "flow_id": "flow_abc123" } }

`flow.executed`

Coarse terminal signal. status is completed, failed, or timeout.

{
  "type": "flow.executed",
  "data": {
    "flow_id": "flow_abc123",
    "execution_id": "exec_001",
    "status": "completed",
    "step_count": 8
  }
}

`flow.execution.started`

{
  "type": "flow.execution.started",
  "data": {
    "flow_id": "flow_abc123",
    "execution_id": "exec_001",
    "node_count": 12,
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

`flow.execution.completed`

{
  "type": "flow.execution.completed",
  "data": {
    "flow_id": "flow_abc123",
    "execution_id": "exec_001",
    "step_count": 8,
    "duration_ms": 5200,
    "timestamp": "2026-03-08T12:00:05Z"
  }
}

`flow.execution.failed`

{
  "type": "flow.execution.failed",
  "data": {
    "flow_id": "flow_abc123",
    "execution_id": "exec_001",
    "error": "node http_request failed: 502",
    "step_count": 3,
    "duration_ms": 1300,
    "timestamp": "2026-03-08T12:00:01Z"
  }
}

Verification Events

The platform uses the verification.* prefix (not verify.*).

`verification.sent`

{
  "type": "verification.sent",
  "data": {
    "verification_id": "vrf_3f1c0b2a8e4d4f7a9c2b1e6d5a4c3b2a",
    "channel": "sms",
    "to": "+14155552671"
  }
}

When a SIM-swap soft warning is detected, sim_swap_warning: true is included alongside the payload above.

`verification.approved`

{
  "type": "verification.approved",
  "data": {
    "verification_id": "vrf_3f1c0b2a8e4d4f7a9c2b1e6d5a4c3b2a",
    "channel": "sms",
    "to": "+14155552671"
  }
}

For Silent Verification (SIM-card-network-binding flow), channel is "silent".

`verification.failed`

{
  "type": "verification.failed",
  "data": {
    "verification_id": "vrf_3f1c0b2a8e4d4f7a9c2b1e6d5a4c3b2a",
    "channel": "sms",
    "to": "+14155552671"
  }
}

verification.failed is emitted only when verification fails because the code was entered incorrectly too many times (attempts exhausted). data carries only the fields above — there is no reason field. Do not branch on a reason value; treat any verification.failed event as the attempts-exhausted case. Pre-send security and fraud blocks are not reported through verification.failed. They are refused before any verification row exists (no verification_id, no OTP sent, no code checked), so reporting them as a failed verification would deliver a phantom failure for a verification that never started. Handle them as follows:

Fraud blocks are delivered as their own verification.fraud_blocked webhook (documented below).
SIM-swap blocks and line-type blocks emit no webhook at all — they surface only as synchronous API errors. Read the error response body on the send request (see below).

`verification.fraud_blocked`

Emitted when the pre-send Fraud Guard refuses an OTP send (the destination scored as fraudulent under the tenant’s fraud policy). This fires before any verification row is created or OTP is dispatched, so the payload deliberately has no verification_id.

{
  "type": "verification.fraud_blocked",
  "data": {
    "channel": "sms",
    "to": "+14155552671",
    "reason": "fraud_blocked",
    "risk_score": 87,
    "fraud_reasons": ["risk_block", "roaming"]
  }
}

The same send is also refused synchronously with a 403 VERIFY_FRAUD_BLOCKED API error whose details carry risk_score and reasons.

SIM-swap and line-type blocks (no webhook)

Pre-send SIM-swap and line-type policy blocks do not dispatch any webhook. They are returned synchronously as API errors on the verification send request, so subscribers must read the error response body rather than wait for an event:

SIM-swap block — 403 SIM_SWAP_DETECTED; details carry last_swap_date and block_window_hours.
Line-type block — 422 VERIFY_LINE_TYPE_BLOCKED; details carry line_type, channel, and policy_slot.

Number / Porting Events

`number.purchased`

{
  "type": "number.purchased",
  "data": {
    "number_id": "num_abc123",
    "phone_number": "+14155550100"
  }
}

reclaimed: true is included when the number was re-claimed from the parking pool.

`number.released`

{ "type": "number.released", "data": { "number_id": "num_abc123" } }

`number.ported`

{
  "type": "number.ported",
  "data": {
    "porting_id": "port_001",
    "numbers": ["+14155550100", "+14155550101"],
    "carrier": "Verizon",
    "provider": "telnyx",
    "status": "submitted"
  }
}

`porting.request.cancelled`

Customer aborted an in-flight port.

{
  "type": "porting.request.cancelled",
  "data": {
    "porting_request_id": "port_001",
    "numbers": ["+14155550100"],
    "cancelled_from_status": "submitted"
  }
}

Conversation Events

`conversation.created`

{
  "type": "conversation.created",
  "data": {
    "conversation_id": "conv_001",
    "campaign_id": "camp_abc123",
    "agent_id": "agt_abc123",
    "contact_id": "con_xyz789",
    "recipient": "+14155552671",
    "source": "journey"
  }
}

List / Segment Events

list.updated fires for both metadata edits and membership changes. Every payload carries a change discriminator so you can tell why the list updated without diffing state: metadata (rename / description edit), member_added and member_removed (single membership change, each carries contact_id), or members_added (bulk add, carries added_count). The list_id and current name are always present. Membership events fire only when the list actually changed — an idempotent re-add or a no-op remove emits nothing.

{ "type": "list.created", "data": { "list_id": "list_abc", "name": "VIP Leads" } }
{ "type": "list.updated", "data": { "list_id": "list_abc", "name": "VIP Leads (renamed)", "change": "metadata" } }
{ "type": "list.updated", "data": { "list_id": "list_abc", "name": "VIP Leads", "change": "member_added", "contact_id": "con_xyz789" } }
{ "type": "list.updated", "data": { "list_id": "list_abc", "name": "VIP Leads", "change": "members_added", "added_count": 25 } }
{ "type": "list.updated", "data": { "list_id": "list_abc", "name": "VIP Leads", "change": "member_removed", "contact_id": "con_xyz789" } }
{ "type": "list.deleted", "data": { "list_id": "list_abc" } }
{ "type": "segment.created", "data": { "segment_id": "seg_abc" } }
{ "type": "segment.deleted", "data": { "segment_id": "seg_abc" } }

Webhook Endpoint Events

{ "type": "webhook_endpoint.created", "data": { "endpoint_id": "wh_abc" } }
{ "type": "webhook_endpoint.updated", "data": { "endpoint_id": "wh_abc" } }
{ "type": "webhook_endpoint.deleted", "data": { "endpoint_id": "wh_abc" } }

Billing Events

`subaccount.spend_cap.threshold`

Fired to the parent (reseller) org when a capped subaccount’s month-to-date spend crosses 50%, 80%, or 100% of its monthly spend cap. Each threshold fires once per billing period and re-arms at the start of the next month. The 100 crossing carries enforced: true — the cap is now stopping outbound traffic for that subaccount. Subaccounts with no cap set are never evaluated. usage_percent is the floored month-to-date percentage of the cap (it can exceed 100 once spend runs past the ceiling).

{
  "type": "subaccount.spend_cap.threshold",
  "data": {
    "subaccount_id": "org_child123",
    "subaccount_name": "Acme Retail",
    "parent_organization_id": "org_reseller456",
    "threshold_percent": 80,
    "usage_percent": 85,
    "monthly_spend_cap_cents": 50000,
    "month_to_date_spend_cents": 42500,
    "period": "2026-06",
    "enforced": false,
    "evaluated_at": "2026-06-12T03:15:00Z"
  }
}

`balance.low`

{
  "type": "balance.low",
  "data": {
    "remaining_cents": 75,
    "remaining_usd": "0.75",
    "threshold_cents": 100,
    "triggered_by": "message:msg_abc123",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

`balance.topped_up`

{
  "type": "balance.topped_up",
  "data": {
    "organization_id": "org_abc",
    "amount_cents": 5000,
    "currency": "usd"
  }
}

`credits.purchased` (deprecated alias of `balance.topped_up`)

Same data plus a legacy credits field. Prefer balance.topped_up for new integrations.

Channel Failover Events

`channel.failover`

Fired when a messaging channel’s primary provider failed and Orbit automatically switched to a backup.

{
  "type": "channel.failover",
  "data": {
    "channel": "sms",
    "failed_provider": "telnyx",
    "active_provider": "jasmin",
    "error_message": "HTTP 502 from carrier",
    "message_id": "msg_abc123",
    "attempt_index": 1,
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Push Events

`push.delivered`

Mobile / web SDK acknowledged a push was rendered on-device.

{
  "type": "push.delivered",
  "data": {
    "id": "push_abc123",
    "device_token_id": "dt_abc",
    "at": "2026-03-08T12:00:01Z"
  }
}

`push.opened`

User tapped the push and the SDK reported the open.

{
  "type": "push.opened",
  "data": {
    "id": "push_abc123",
    "device_token_id": "dt_abc",
    "at": "2026-03-08T12:01:30Z"
  }
}

Number Masking (Proxy) Events

`proxy.session.created`

{
  "type": "proxy.session.created",
  "data": {
    "session_id": "psess_abc",
    "proxy_number": "+14155550100",
    "participant_a": "+14155552671",
    "participant_b": "+14155558888",
    "expires_at": "2026-03-08T13:00:00Z"
  }
}

`proxy.session.closed`

{
  "type": "proxy.session.closed",
  "data": {
    "session_id": "psess_abc",
    "proxy_number": "+14155550100",
    "closed_at": "2026-03-08T12:45:00Z"
  }
}

`proxy.message.forwarded`

{
  "type": "proxy.message.forwarded",
  "data": {
    "session_id": "psess_abc",
    "proxy_number": "+14155550100",
    "from_participant": "+14155552671",
    "to_participant": "+14155558888",
    "channel": "sms"
  }
}

WhatsApp Events

WhatsApp events mirror Meta WABA webhook fields. Each fires after Orbit ingests the corresponding Meta callback and persists the upstream change. Payloads carry the relevant waba_id / phone_number_id so consumers can correlate to their own Meta tooling.

WhatsApp Calling

The lifecycle events (whatsapp.call.connected, _accepted, _terminated) share the same payload shape; the legacy whatsapp.call.received is also dispatched on every transition for backward-compatible consumers.

{
  "type": "whatsapp.call.connected",
  "data": {
    "waba_id": "1234567890",
    "phone_number_id": "0987654321",
    "meta_call_id": "wacid_…",
    "wa_call_log_id": "wacall_…",
    "direction": "inbound",
    "from": "+14155552671",
    "to": "+18005551234",
    "phase": "connect",
    "meta_event": "connect",
    "meta_status": null,
    "duration_seconds": null,
    "biz_opaque_callback_data": null
  }
}

whatsapp.call.permission_granted:

{
  "type": "whatsapp.call.permission_granted",
  "data": {
    "contact_id": "con_abc",
    "waba_id": "1234567890",
    "phone_number_id": "0987654321",
    "source": "inbound_call",
    "ttl_seconds": 86400,
    "meta_call_id": "wacid_…"
  }
}

whatsapp.call.permission_revoked:

{
  "type": "whatsapp.call.permission_revoked",
  "data": {
    "contact_id": "con_abc",
    "waba_id": "1234567890",
    "phone_number_id": "0987654321",
    "meta_call_id": "wacid_…"
  }
}

WhatsApp Templates

Sample for whatsapp.template.approved (others share the same shape with the relevant Meta payload echoed under details):

{
  "type": "whatsapp.template.approved",
  "data": {
    "waba_id": "1234567890",
    "template_id": "tpl_abc",
    "template_name": "appointment_reminder_v1",
    "language": "en_US",
    "details": { "...": "Meta event payload" }
  }
}

whatsapp.template.rejected includes details.reason with Meta’s rejection text.

WhatsApp Account / Business / Phone

whatsapp.account.update, whatsapp.account.banned, whatsapp.account.restricted, whatsapp.account.alert, whatsapp.account.review_update, whatsapp.account.settings_update, whatsapp.business.status_update, whatsapp.phone.quality_update, whatsapp.phone.name_update, whatsapp.capability.update, whatsapp.security.alert, whatsapp.flow.status_change, whatsapp.quality.changed — all share the shape:

{
  "type": "whatsapp.account.banned",
  "data": {
    "waba_id": "1234567890",
    "details": { "...": "Meta event payload" }
  }
}

WhatsApp Data Subject Requests

{
  "type": "whatsapp.data.export_request",
  "data": {
    "waba_id": "1234567890",
    "user": "+14155552671",
    "details": { "...": "Meta payload" }
  }
}

whatsapp.data.delete_request follows the same shape.

WhatsApp v25 fields

whatsapp.automatic_events, whatsapp.history, whatsapp.partner_solutions, whatsapp.payment_configuration_update, whatsapp.smb.app_state_sync, whatsapp.smb.message_echoes, whatsapp.tracking_events, whatsapp.user.preferences, whatsapp.group.lifecycle_update, whatsapp.group.participants_update, whatsapp.group.settings_update, whatsapp.group.status_update — each carries the original Meta event payload under details:

{
  "type": "whatsapp.tracking_events",
  "data": {
    "waba_id": "1234567890",
    "details": { "...": "Meta event payload" }
  }
}

WhatsApp Order

whatsapp.order.received — conversational-commerce order capture. Fires once per inbound type === "order" message — i.e. when a buyer browses the merchant’s Meta Commerce catalog inside the WhatsApp thread and taps Send in the checkout drawer. Carries the normalized cart so merchants can drive fulfilment / capture payment in their own systems off a single dedicated event (previously the order only rode the generic message.received fan-out inside message metadata). De-duplicated against Meta webhook retries — it fires only on the first delivery of a given wamid.

{
  "type": "whatsapp.order.received",
  "data": {
    "message_id": "msg_abc123",
    "contact_id": "con_abc",
    "from": "+14155552671",
    "whatsapp_bsuid": "0987654321",
    "catalog_id": "cat_123456",
    "buyer_text": "Please ship to my home address",
    "items": [
      {
        "product_retailer_id": "SKU-001",
        "quantity": 2,
        "unit_price": 1299,
        "currency": "USD",
        "line_total": 2598
      }
    ],
    "line_count": 1,
    "item_count": 2,
    "subtotal": 2598,
    "currency": "USD",
    "mixed_currency": false,
    "occurred_at": "2026-03-08T12:05:00Z"
  }
}

Monetary fields (unit_price, line_total, subtotal) are minor units of currency. When a cart mixes currencies, mixed_currency is true and subtotal is omitted — read the per-item line_total values instead.

Survey Events

Standalone surveys product (surveys) response webhooks. Tenant-scoped — every emit flows through dispatchTenantWebhook, so subscribers only see responses for their own organization.

`survey.response.detractor`

CXaaS closed-loop survey feedback — fires when a recipient-facing survey response lands at detractor level (NPS ≤ 6 of 10, CSAT ≤ 6 of 10). Fires at most once per response, gated on the first recording of a responded_at (a repeat tap of the same signed link is idempotent and does not re-fire). Wire CRMs (Salesforce / HubSpot / Zendesk) to this event to open a case/activity within seconds of the detractor response.

{
  "type": "survey.response.detractor",
  "data": {
    "survey_id": "srv_abc123",
    "response_id": "resp_def456",
    "contact_id": "con_abc",
    "survey_type": "nps",
    "score": 3,
    "threshold": 6,
    "channel": "email",
    "comment": "Shipping took far too long.",
    "responded_at": "2026-03-08T12:06:00Z"
  }
}

survey_type is one of "nps", "csat", or "ces". score is the raw response value and threshold the detractor cutoff that was crossed; comment is null when the respondent left no free-text.

Calendly Events

Re-emitted when Calendly delivers a scheduling event to your connected Calendly integration. The four calendly.* types map one-to-one to Calendly’s own event names, with the raw Calendly type repeated in data.event_type:

Event	Fires when
`calendly.invitee.created`	An invitee books a meeting.
`calendly.invitee.canceled`	An invitee cancels a booked meeting.
`calendly.invitee_no_show.created`	An invitee is marked as a no-show.
`calendly.routing_form_submission.created`	A Calendly routing form is submitted.

All four share one payload shape:

{
  "type": "calendly.invitee.created",
  "data": {
    "event_type": "invitee.created",
    "event_uri": "https://api.calendly.com/scheduled_events/EVENT_UUID/invitees/INVITEE_UUID",
    "scheduled_event_uri": "https://api.calendly.com/scheduled_events/EVENT_UUID",
    "invitee_email": "person@example.com",
    "contact_id": "cnt_abc123",
    "organization_id": "org_abc123",
    "occurred_at": "2026-03-08T12:00:00Z"
  }
}

contact_id is the Orbit contact matched or created from the invitee email, or null when no match was made. invitee_email is null for routing-form submissions that carry no email. scheduled_event_uri points at the parent Calendly event; event_uri points at the specific invitee or submission record. The delivery is idempotent on Calendly’s event identity — a duplicate Calendly redelivery does not re-fire this webhook.

Video Events

Real-time video room lifecycle, recording, ingress, and transcription webhooks. Tenant-scoped — every emit flows through dispatchTenantWebhook. These mirror the Daily / Twilio Video / Agora callbacks so a dashboard can wake on a room start, a guest join, or a finished recording without polling the SFU.

`video.room.started` / `video.room.ended`

Fire when a video room opens and closes.

{
  "type": "video.room.started",
  "data": {
    "room_id": "vroom_abc123",
    "room_sid": "RM_abc123",
    "room_name": "weekly-team-sync"
  }
}

video.room.ended carries the same room_id, room_sid, and room_name, plus a full set of end-of-call fields:

{
  "type": "video.room.ended",
  "data": {
    "room_id": "vroom_abc123",
    "room_sid": "RM_abc123",
    "room_name": "weekly-team-sync",
    "duration_seconds": 1840,
    "participant_seconds": 5230,
    "max_participants": 4,
    "total_join_events": 6,
    "end_reason": "last_participant_left",
    "org_id": "org_abc123"
  }
}

Field	Description
`duration_seconds`	Wall-clock lifetime of the room, from first start to close.
`participant_seconds`	Summed connected time across every participant — the billable participant-minute source.
`max_participants`	Peak concurrent participants observed during the room’s lifetime.
`total_join_events`	Count of join events (a participant who rejoins counts each time).
`end_reason`	Why the room closed. Subscribe to this to tell a never-connected ghost from a normal finish or an operator close.
`org_id`	The Orbit organization that owns the room.

end_reason is one of failed_no_connect (room opened but no participant ever connected), last_participant_left (emptied out normally), operator_end (closed from the dashboard or API), timeout (hit the configured max duration), room_finished (SFU closed the room), or error (closed after an internal failure). It mirrors the room’s persisted termination classification 1:1. room_sid is omitted when the SFU never assigned one.

`video.participant.joined` / `video.participant.left`

Fire when a participant joins or leaves a room.

{
  "type": "video.participant.joined",
  "data": {
    "room_id": "vroom_abc123",
    "identity": "user_42",
    "display_name": "Jordan Lee"
  }
}

video.participant.left carries { room_id, identity }.

`video.recording.completed` / `video.recording.failed`

Twilio-Video-parity completion callbacks for a room recording.

{
  "type": "video.recording.completed",
  "data": {
    "room_id": "vroom_abc123",
    "recording_id": "vrec_abc123",
    "recording_url": "https://storage.orbit.devotel.io/rec/abc123.mp4",
    "recording_urls": [
      "https://storage.orbit.devotel.io/rec/abc123.mp4"
    ],
    "recording_qc": { "status": "ok", "reasons": [] }
  }
}

recording_id is the stable id for the recording, recording_url is the primary artifact, and recording_urls lists every artifact URL for the room (a single-file recording collapses to one entry that matches recording_url). recording_qc is only present once quality scoring has run. video.recording.failed carries { room_id, recording_url: null, status, reasons }.

`video.recording.degraded`

Recording QC verdict — fires alongside video.recording.completed when the artifact lands but the quality scorer flags it. Subscribe to this when you want strict missing / degraded semantics so silent recording loss is caught within minutes of call-end.

{
  "type": "video.recording.degraded",
  "data": {
    "room_id": "vroom_abc123",
    "session_id": "vsess_abc123",
    "status": "degraded",
    "reasons": ["zero_byte_file"],
    "recording_url": null
  }
}

status is "missing" or "degraded"; recording_url is null when no artifact was produced.

`video.active_speakers.changed`

Fires whenever the SFU’s active-speaker set changes. The speakers array is pre-sorted descending by audio level, so speakers[0] is the dominant speaker. An empty array signals silence. Not persisted per event — aggregate downstream for talk-time rollups.

{
  "type": "video.active_speakers.changed",
  "data": {
    "room_id": "vroom_abc123",
    "room_name": "tenant_xyz_vroom_abc123",
    "speakers": [
      { "identity": "user_42", "name": "Jordan Lee", "audio_level": 0.82, "active": true }
    ],
    "dominant_speaker_identity": "user_42"
  }
}

`video.ingress.started` / `video.ingress.ended` / `video.ingress.failed`

RTMP / WHIP / URL-pull ingress lifecycle. Subscribe to video.ingress.started to wake live on a broadcast source connecting, and to the ended / failed pair for terminal states.

{
  "type": "video.ingress.started",
  "data": {
    "room_id": "vroom_abc123",
    "ingress_id": "ing_abc123",
    "ingress_name": "Main stage RTMP",
    "input_type": "rtmp",
    "room_name": "tenant_xyz_vroom_abc123",
    "participant_identity": "WHIP_abc123"
  }
}

video.ingress.ended adds status ("complete" or "error"), error, and duration_seconds. video.ingress.failed carries a required error string. A source that errors fires both video.ingress.failed and video.ingress.ended with status: "error".

`video.recording.transcript_ready`

Async post-meeting transcription of a room recording is complete (Deepgram). Zoom / Daily.co transcript-ready parity.

{
  "type": "video.recording.transcript_ready",
  "data": {
    "room_id": "vroom_abc123",
    "recording_id": "rec_abc123",
    "transcript": "Speaker 1: Thanks for joining...",
    "transcript_chars": 4821,
    "transcribed_at": "2026-03-08T12:30:00Z"
  }
}

`video.caption.segment`

Fired per completed (final) live caption line during an active room, so a downstream system can consume captions in real time — a live translation relay, a compliance-capture pipeline, an accessibility feed, or live-blogging — instead of waiting for the post-recording video.recording.transcript_ready event. Interim/partial results are never emitted. room_id is the same room id every other video event carries, so you can correlate segments with the room’s lifecycle events.

{
  "type": "video.caption.segment",
  "data": {
    "room_id": "550e8400-e29b-41d4-a716-446655440000",
    "room_name": "weekly-standup",
    "identity": "alice_example_com",
    "participant_name": "Alice",
    "text": "Thanks everyone for joining today.",
    "language": "en",
    "is_final": true,
    "ts": 1751846400000,
    "start_ms": null,
    "end_ms": null,
    "emitted_at": "2026-07-07T12:30:00Z"
  }
}

Participant moderation events

Fired when a host or moderator acts on a participant, or when a participant’s in-room state changes — so you can drive a moderation UI, a compliance-logging pipeline, or webinar tooling programmatically (parity with Twilio Video / LiveKit / Agora participant-event streams). The events are:

Event	Fires when
`video.participant.muted`	A moderator force-mutes a participant’s `audio` or `video` track.
`video.participant.unmuted`	A moderator clears a participant’s force-mute.
`video.participant.kicked`	A moderator boots a participant (ephemeral — the identity can rejoin).
`video.participant.banned`	A moderator persistently bars an identity from rejoining the room.
`video.participant.unbanned`	A moderator lifts a persistent ban.
`video.participant.role_changed`	A participant’s in-meeting role changes (`attendee` / `presenter` / `moderator`).
`video.participant.spotlighted`	A moderator pins a participant as the foregrounded track for everyone.
`video.room.spotlight_cleared`	A moderator clears the room spotlight (room-level — no `identity`).
`video.participant.hand_raised`	A participant raises their hand (or a moderator raises it for them).
`video.participant.hand_lowered`	A participant’s raised hand is lowered.

Every payload carries room_id (the same room id every other video event carries, so you can correlate against video.room.started / video.participant.joined), the server-stamped actor_user_id and actor_role of the moderator who performed the action, and emitted_at. Per-event fields: identity (the affected participant — absent on the room-level video.room.spotlight_cleared), kind (audio / video, on mute / unmute), reason (on ban), role (on role change), and hand_id (on hand raised).

{
  "type": "video.participant.muted",
  "data": {
    "room_id": "550e8400-e29b-41d4-a716-446655440000",
    "identity": "alice_example_com",
    "kind": "audio",
    "actor_user_id": "user_host_1",
    "actor_role": "admin",
    "emitted_at": "2026-07-07T12:30:00Z"
  }
}

{
  "type": "video.participant.role_changed",
  "data": {
    "room_id": "550e8400-e29b-41d4-a716-446655440000",
    "identity": "alice_example_com",
    "role": "presenter",
    "actor_user_id": "user_host_1",
    "actor_role": "admin",
    "emitted_at": "2026-07-07T12:30:00Z"
  }
}

Supervisor Events

Live-call supervisor takeover (warm-handoff) lifecycle. Tenant-scoped.

`supervisor.takeover_requested`

A supervisor initiates a takeover of a live call.

{
  "type": "supervisor.takeover_requested",
  "data": {
    "id": "takeover_abc123",
    "call_id": "call_abc123",
    "initiated_by": "user_supervisor_1",
    "agent_being_replaced": "user_agent_7",
    "reason": "escalation",
    "state": "requested",
    "organization_id": "org_abc"
  }
}

`supervisor.takeover_completed`

The supervisor successfully takes over and becomes the active party.

{
  "type": "supervisor.takeover_completed",
  "data": {
    "id": "takeover_abc123",
    "call_id": "call_abc123",
    "initiated_by": "user_supervisor_1",
    "agent_being_replaced": "user_agent_7",
    "reason": "escalation",
    "state": "completed",
    "organization_id": "org_abc",
    "context_preserved": true
  }
}

`supervisor.takeover_failed`

The attempt failed (e.g. a REST error during the leg-swap).

{
  "type": "supervisor.takeover_failed",
  "data": {
    "id": "takeover_abc123",
    "call_id": "call_abc123",
    "reason": "jambonz_rest_error",
    "organization_id": "org_abc"
  }
}

`supervisor.takeover_cancelled`

The takeover was cancelled (call ended before handoff completed, or the supervisor aborted).

{
  "type": "supervisor.takeover_cancelled",
  "data": {
    "id": "takeover_abc123",
    "state": "cancelled"
  }
}

Voice Queue (ACD) Events

Contact-center queue-routing lifecycle (Five9 / Genesys parity). Wire these for screen-pop, after-call work, and abandonment-rescue flows without polling the queue-entries endpoint. Tenant-scoped.

`queue.call.queued`

Fires the instant a call enters a queue.

{
  "type": "queue.call.queued",
  "data": {
    "queue_id": "queue_abc123",
    "call_id": "call_abc123",
    "entry_id": "qe_abc123",
    "required_skills": ["billing", "es"],
    "priority": 5,
    "organization_id": "org_abc",
    "caller_number": "+14155552671"
  }
}

`queue.call.assigned`

Fires the moment an agent is selected, before the origination call returns — drives screen-pop.

{
  "type": "queue.call.assigned",
  "data": {
    "queue_id": "queue_abc123",
    "call_id": "call_abc123",
    "entry_id": "qe_abc123",
    "agent_id": "user_agent_7",
    "wait_seconds": 42
  }
}

`queue.call.abandoned`

Fires when the caller hangs up before assignment, or the ACD reconciler sweeps a stuck row.

{
  "type": "queue.call.abandoned",
  "data": {
    "queue_id": "queue_abc123",
    "call_id": "call_abc123",
    "entry_id": "qe_abc123",
    "end_reason": "caller_hangup",
    "wait_seconds": 73
  }
}

`queue.alert_rule_fired`

A user-configured supervisor-wallboard alert rule (action webhook) crossed its threshold. Operators may override the emitted event slug per rule via the rule’s delivery_config.webhook_event_type.

{
  "type": "queue.alert_rule_fired",
  "data": {
    "queue_id": "queue_abc123",
    "rule_id": "rule_abc123",
    "rule_name": "ASA over 30s",
    "metric": "asa_seconds",
    "op": "gt",
    "threshold": 30,
    "actual_value": 47,
    "ts": "2026-03-08T12:00:00Z"
  }
}

`agent.state.changed`

Contact-center agent presence transition (WFM / RTA integration parity). Distinct from the AI-agent lifecycle events — this carries the CCaaS from/to presence pair the supervisor wallboard sees.

{
  "type": "agent.state.changed",
  "data": {
    "agent_id": "user_agent_7",
    "from_state": "available",
    "to_state": "away",
    "reason_code": "lunch",
    "changed_by": "user_agent_7",
    "changed_at": "2026-03-08T12:00:00Z"
  }
}

`wallboard.sla_warning`

Fires when a queue’s predicted total wait crosses 90% of its maxWaitSeconds SLA target. One event per breach window (30s per-queue dedup). Wire to PagerDuty / Opsgenie / on-call Slack.

{
  "type": "wallboard.sla_warning",
  "data": {
    "queue_id": "queue_abc123",
    "queue_name": "Support — Tier 1",
    "waiting": 6,
    "longest_wait_seconds": 110,
    "median_handle_time_seconds": 240,
    "predicted_wait_seconds": 350,
    "sla_target_seconds": 400,
    "threshold_ratio": 0.9,
    "agents_available": 1,
    "agents_total": 8
  }
}

`wfm.adherence_breach`

Fires when an agent’s intraday adherence ratio drops below the out-of-adherence threshold (default 85%). At most once per ~5 minutes per agent. NICE IEX / Verint / Genesys WFM parity.

{
  "type": "wfm.adherence_breach",
  "data": {
    "agent_id": "user_agent_7",
    "date": "2026-03-08",
    "scheduled_seconds": 28800,
    "elapsed_seconds": 14400,
    "in_adherent_state_seconds": 11800,
    "adherence_ratio": 0.819,
    "adherence_percent": 81.9,
    "threshold": 0.85,
    "threshold_percent": 85,
    "current_state": "unavailable",
    "current_state_started_at": "2026-03-08T11:50:00Z"
  }
}

Post-Call IVR Survey Events

IVR-captured post-call CSAT / NPS responses (distinct from the standalone Surveys product above). Fires once per captured response — the de-dup path does not re-fire. Wire CRMs to auto-create activities / cases on a low CSAT or detractor NPS within seconds of the call ending. Tenant-scoped.

`survey.csat.response_recorded` / `survey.nps.response_recorded`

Siblings carry the same shape — discriminate by type. CSAT uses a 1-5 scale, NPS uses 0-10.

{
  "type": "survey.csat.response_recorded",
  "data": {
    "survey_id": "srv_abc123",
    "response_id": "resp_abc123",
    "call_id": "call_abc123",
    "score": 2,
    "digit_pressed": "2",
    "attempts": 1,
    "channel": "ivr_voice",
    "agent_user_id": "user_agent_7",
    "contact_id": "con_abc",
    "responded_at": "2026-03-08T12:06:00Z",
    "satisfaction_bucket": "dissatisfied"
  }
}

CSAT responses carry satisfaction_bucket (satisfied / neutral / dissatisfied); NPS responses instead carry nps_bucket (promoter / passive / detractor). Idempotent on the (survey_id, call_id) tuple, so a jambonz retry does not double-fire.

Conversation & Inbox Events

AI- and rule-driven conversation lifecycle for the inbox / CXaaS surface. Tenant-scoped.

`conversation.closed`

A conversation transitioned to a closed/resolved terminal state.

{
  "type": "conversation.closed",
  "data": {
    "conversation_id": "conv_abc123",
    "organization_id": "org_abc"
  }
}

`conversation.disposed`

The auto-disposition engine automatically closed/resolved a conversation.

{
  "type": "conversation.disposed",
  "data": {
    "conversation_id": "conv_abc123",
    "disposition": "resolved_no_action",
    "organization_id": "org_abc"
  }
}

`conversation.scored`

A conversation received a quality-management (QM) score.

{
  "type": "conversation.scored",
  "data": {
    "conversation_id": "conv_abc123",
    "score": 87,
    "scorer_id": "scorecard_abc",
    "criteria": { "greeting": 1, "resolution": 0.8 },
    "organization_id": "org_abc"
  }
}

`conversation.csat_detractor`

A customer-facing CSAT (1-5, score under 3) or NPS (0-10, score 6 or below) submission lands and qualifies as a detractor — a “go-recover-this-customer” alert distinct from conversation.scored. Gated on the first write, so a resubmission does not double-fire.

{
  "type": "conversation.csat_detractor",
  "data": {
    "conversation_id": "conv_abc123",
    "score_type": "csat",
    "score": 2,
    "threshold": 3,
    "scored_at": "2026-03-08T12:06:00Z",
    "auto_reopened": false
  }
}

auto_reopened is true when the tenant opted into settings.csat.auto_reopen_on_detractor and the reopen succeeded.

`conversation.synthesized`

A structured post-chat AI summary landed on the conversation (Intercom Fin / Sierra parity). Mirrors the voice-surface call.synthesized shape so a CRM/CDP can attach the summary without re-summarising.

{
  "type": "conversation.synthesized",
  "data": {
    "conversation_id": "conv_abc123",
    "contact_id": "con_abc",
    "summary": "Customer asked about a duplicate charge; refund issued.",
    "key_points": ["duplicate charge", "refund"],
    "action_items": ["confirm refund landed"],
    "resolution": "refund_issued",
    "generated_at": "2026-03-08T12:10:00Z"
  }
}

`conversation.deflected` / `ticket.deflected`

An AI knowledge-base auto-reply resolved a conversation without a human. Subscribe to both conversation.closed and conversation.deflected to separate AI-resolved from human-resolved volume (AI-containment-rate / deflection KPIs). ticket.deflected is the symmetrical alias for CRMs that model conversations as tickets — same payload, same code path.

{
  "type": "conversation.deflected",
  "data": {
    "conversation_id": "conv_abc123",
    "source": "ai_kb_auto_deflect",
    "confidence": 0.91,
    "threshold": 0.8,
    "knowledge_base_id": "kb_abc",
    "document_id": "doc_abc",
    "chunk_index": 3,
    "deflected_at": "2026-03-08T12:05:00Z"
  }
}

`conversation.ai_review_needed`

An AI-resolved conversation received a low CSAT — pairs every deflection with a satisfaction check and auto-flags “AI deflected but the customer was unhappy” for human review and retraining.

{
  "type": "conversation.ai_review_needed",
  "data": {
    "conversation_id": "conv_abc123",
    "score": 2,
    "score_max": 5,
    "threshold": 3,
    "ai_resolution_source": "deflected_via_kb",
    "ai_confidence": 0.88,
    "intent": "billing_question",
    "flagged_at": "2026-03-08T12:07:00Z"
  }
}

CDP Events

Customer-data-platform ingestion, identity resolution, computed-trait, and segment-membership webhooks (Segment / RudderStack / Hightouch parity). Tenant-scoped.

`cdp.event.ingested`

Fires after a server-to-server /cdp/track or /cdp/identify payload is verified, persisted, and identity-resolved.

{
  "type": "cdp.event.ingested",
  "data": {
    "event_id": "cdpevt_abc123",
    "type": "track",
    "name": "Order Completed",
    "user_id": "user_42",
    "anonymous_id": "anon_abc",
    "contact_id": "con_abc",
    "properties": {
      "value": 99.99,
      "currency": "USD"
    },
    "received_at": "2026-03-08T12:00:00Z"
  }
}

`cdp.identity.resolved`

Fires after an identify call resolves an anonymous identity onto a contact — for downstream CDP-to-CDP federation.

{
  "type": "cdp.identity.resolved",
  "data": {
    "event_id": "cdpevt_abc123",
    "contact_id": "con_abc",
    "created": false,
    "user_id": "user_42",
    "anonymous_id": "anon_abc"
  }
}

created is true when the identify call created a new contact.

`cdp.tracking_plan.violation_spike`

Proactive data-quality alert — fires when a tenant’s tracking-plan / event-schema violation volume crosses the alert threshold in the rolling window (Segment Protocols / RudderStack Data Governance parity).

{
  "type": "cdp.tracking_plan.violation_spike",
  "data": {
    "window_count": 142,
    "threshold": 100,
    "window_seconds": 300,
    "sample_event_name": "Order Completed",
    "sample_violation_type": "missing_required_property",
    "enforcement": "warn",
    "detected_at": "2026-03-08T12:00:00Z"
  }
}

`contact.trait_changed`

A computed-trait value transition for a single contact (Hightouch / Segment computed-traits parity) — fires when the realtime recompute pipeline observes a change to a contact’s trait. Critical for journey triggers (e.g. a contact crossing ltv >= 1000).

{
  "type": "contact.trait_changed",
  "data": {
    "contact_id": "con_abc",
    "trait_name": "ltv",
    "old_value": 940,
    "new_value": 1080,
    "computed_at": "2026-03-08T12:00:00Z"
  }
}

`contact.entered_segment` / `contact.exited_segment`

Fires once per contact who crosses an operator-defined segment’s membership boundary on its auto_refresh tick (distinct from the predictive contact.segment_changed). Wire to Braze / Customer.io / Iterable to mirror audience membership in real time.

{
  "type": "contact.entered_segment",
  "data": {
    "contact_id": "con_abc",
    "segment_id": "seg_abc",
    "segment_name": "High-value EU",
    "direction": "entered",
    "occurred_at": "2026-03-08T12:00:00Z"
  }
}

contact.exited_segment carries the same shape with direction: "exited".

Integration Health Events

Nango-managed CRM / helpdesk / automation connector health. Surfaces a previously-silent failure class so you learn the moment a tenant’s data stops flowing rather than on the next manual “Test connection”. Grouped under the integration prefix in the subscribe UI. Tenant-scoped.

`integration.auth_failed`

A stored OAuth refresh token was rejected (revoked, scope changed, account de-provisioned) — the connection silently rots while the UI still shows “Connected”.

{
  "type": "integration.auth_failed",
  "data": {
    "connection_id": "conn_abc123",
    "provider_config_key": "salesforce",
    "reason": "refresh_token_rejected",
    "occurred_at": "2026-03-08T12:00:00Z"
  }
}

`integration.sync_failed`

A sync errored (token expired mid-sync, upstream 5xx, flow-script failure). Fired from two paths, distinguished by reason. reason is a stable platform-side classifier, never raw upstream provider error text. The payload shape depends on which path fired, so branch on reason rather than assuming a field is present. When a specific sync run fails, the event carries the full connection context and reason is sync_failed:

{
  "type": "integration.sync_failed",
  "data": {
    "connection_id": "conn_abc123",
    "provider_config_key": "salesforce",
    "sync_name": "contacts",
    "reason": "sync_failed",
    "occurred_at": "2026-03-08T12:00:00Z"
  }
}

When a connection’s consecutive-failure count crosses the alerting threshold, only the provider is included and reason is consecutive_failure_threshold:

{
  "type": "integration.sync_failed",
  "data": {
    "provider": "salesforce",
    "reason": "consecutive_failure_threshold",
    "occurred_at": "2026-03-08T12:00:00Z"
  }
}

Account & Security Events

`account.fraud.alert`

A customer-subscribable real-time signal that the platform’s fraud / abuse detection acted on your own traffic — toll-fraud / IRSF prefix block, SMS traffic-pumping, SIM-swap heuristic, voice-deepfake high score, or an API-key geo anomaly. The customer-facing fan-out of the same detection decision that lands in the internal fraud queue, so you learn within minutes instead of from the next invoice. All values are PII-scrubbed (phone PREFIX only). Tenant-scoped.

{
  "type": "account.fraud.alert",
  "data": {
    "category": "irsf_blocked",
    "severity": "high",
    "source": "voice",
    "summary": "Blocked outbound dialing to a high-risk IRSF prefix.",
    "details": {
      "phone_prefix": "+88216",
      "correlation_id": "fr_abc123",
      "rule": "irsf_prefix_block",
      "risk_score": 0.94
    },
    "detected_at": "2026-03-08T12:00:00Z"
  }
}

category is one of irsf_blocked, sim_swap_detected, suspicious_campaign_send, voice_deepfake_high_score, or api_key_geo_anomaly. severity is low / medium / high / critical.

`audit.log.created`

Continuous audit-log streaming to a customer SIEM — fires once per append to the audit log, giving SOC teams near-real-time push of every security event to their own sink. HMAC-signed with the same envelope as every other Orbit webhook. Tenant-scoped.

{
  "type": "audit.log.created",
  "data": {
    "audit_id": "audit_abc123",
    "current_hash": "a1b2c3...",
    "organization_id": "org_abc",
    "tenant_id": "11111111-2222-3333-4444-555555555555",
    "user_id": "user_42",
    "action": "number.released",
    "resource": "phone_number",
    "resource_id": "num_abc123",
    "ip_address": "203.0.113.7",
    "user_agent": "Mozilla/5.0 ...",
    "performed_via": "dashboard",
    "details": {}
  }
}

current_hash is the tamper-evident hash-chain digest of the row, so a SIEM can later cross-check the streamed event against the audit-export verify endpoint.

Slack Integration Events

Re-emitted from the tenant Slack webhook receiver after the inbound Slack payload is idempotently persisted, so a tenant integration can react outside Slack’s 3-second ack budget. Grouped under the slack prefix in the subscribe UI. Tenant-scoped.

`slack.slash_command`

A Slack slash command (e.g. /orbit send-sms) was received.

{
  "type": "slack.slash_command",
  "data": {
    "slack_team_id": "T0123",
    "slack_channel_id": "C0123",
    "slack_user_id": "U0123",
    "command": "/orbit",
    "text": "send-sms +14155552671 hello",
    "response_url": "https://hooks.slack.com/commands/...",
    "trigger_id": "1234.5678.abcdef"
  }
}

`slack.event_received`

A Slack Events API callback (app_mention, message, reaction_added, …) was received. The concrete Slack event type is carried in data.slack_event_type rather than folded into the wire name.

{
  "type": "slack.event_received",
  "data": {
    "slack_event_type": "app_mention",
    "slack_team_id": "T0123",
    "slack_channel_id": "C0123",
    "slack_user_id": "U0123",
    "text": "@orbit status",
    "event_id": "Ev0123",
    "event_ts": "1709899200.000100",
    "raw": {}
  }
}

`slack.interactivity`

A Slack interaction (block_actions, view_submission, shortcut, …) was received. The interaction type is carried in data.interactivity_type.

{
  "type": "slack.interactivity",
  "data": {
    "interactivity_type": "block_actions",
    "slack_team_id": "T0123",
    "slack_user_id": "U0123",
    "trigger_id": "1234.5678.abcdef",
    "actions": [],
    "view_callback_id": null,
    "callback_id": null,
    "raw": {}
  }
}

Recording Lifecycle Events

Post-call recording QC, chaptering, and compliance-redaction webhooks (unified across SBC, AI-agent, browser-softphone, conference, and video recordings). Tenant-scoped.

`recording.qc_failed`

A post-finalize QC failure — distinct from recording.failed, which signals an egress abort BEFORE an artifact lands. This fires AFTER the artifact exists but the scorer found degradation (zero-byte file, missing path, late finalize, mime-type mismatch, sub-minimum duration).

{
  "type": "recording.qc_failed",
  "data": {
    "recording_id": "rec_abc123",
    "qc_status": "failed",
    "failed_count": 1,
    "checks": [
      { "name": "duration_min", "passed": false, "value": 0, "threshold": 1, "reason": "zero_byte_file" }
    ],
    "classification": "sbc",
    "started_at": "2026-03-08T12:00:00Z",
    "run_at": "2026-03-08T12:01:00Z"
  }
}

`recording.chapters.ready`

The post-call auto-chaptering pipeline persisted a navigable chapter array onto a recording.

{
  "type": "recording.chapters.ready",
  "data": {
    "call_id": "call_abc123",
    "chapter_count": 5,
    "ready_at": "2026-03-08T12:10:00Z"
  }
}

Carries either call_id or video_room_session_id as the surface key.

`recording.redaction_vault.ready`

The post-call redaction-vault pipeline produced a compliance-safe redacted copy of the call transcript. Gated on the per-tenant settings.compliance.recording_redaction_vault.enabled opt-in. For regulated (HIPAA / PCI-DSS / GDPR) tenants.

{
  "type": "recording.redaction_vault.ready",
  "data": {
    "call_id": "call_abc123",
    "total_redactions": 12,
    "by_category": [
      { "type": "credit_card", "count": 4 },
      { "type": "email", "count": 8 }
    ],
    "compliance_topics": ["pci", "pii"],
    "audio_redaction_segments": [
      { "start_ms": 18400, "end_ms": 21250, "category": "credit_card" }
    ],
    "timestamp": "2026-03-08T12:12:00Z"
  }
}

total_redactions is the count of regulated spans replaced across all categories. by_category lists per-category match counts (only categories with at least one match); type uses the redaction-engine category vocab (credit_card, ssn, email, e164_phone, us_phone, ipv4, ipv6). audio_redaction_segments carries the millisecond audio ranges to mute or beep on playback — each entry is { start_ms, end_ms, category } and only carries timings plus category, never raw transcript values. The list is empty when word-level timings are unavailable. timestamp is the ISO-8601 time the redacted copy was produced.

Voice Analytics Events

`call.hit_voicemail`

An outbound call hit a voicemail / fax (answering-machine detection result). Lets campaigns retry, log, or branch without waiting for the full hangup event.

{
  "type": "call.hit_voicemail",
  "data": {
    "call_id": "call_abc123",
    "amd_type": "machine",
    "detected_at": "2026-03-08T12:00:00Z",
    "direction": "outbound",
    "from": "+15551230000",
    "to": "+15559874321",
    "agent_id": "agt_abc123"
  }
}

amd_type carries the answering-machine-detection result — one of machine, machine_beep_detected, fax, ios_call_screening, or ios_live_voicemail. detected_at is the ISO-8601 time detection landed. direction is outbound or inbound, and from / to are the E.164 call legs (either may be null when the number is withheld). agent_id is present only when the call is tied to an AI voice agent.

`call.transcript_ready`

Fires after post-call sentiment + keyword + topic analysis lands on the call log — a first-class telephony CDP signal the segment-builder can target. Fans to both webhook endpoints and CDP subscriptions.

{
  "type": "call.transcript_ready",
  "data": {
    "call_id": "call_abc123",
    "contact_id": "con_abc",
    "direction": "inbound",
    "duration_sec": 184,
    "sentiment": "negative",
    "sentiment_score": -0.62,
    "keywords": ["refund", "cancel"],
    "topics": ["billing dispute"],
    "transcript_snippet": "I want a refund for the duplicate charge...",
    "analyzed_at": "2026-03-08T12:05:00Z"
  }
}

sentiment is positive / negative / neutral / mixed; sentiment_score ranges -1.0 to +1.0.

Verification Lifecycle Events

Per-attempt and async-fallback verification webhooks. Tenant-scoped.

`verification.checked`

Fires on EVERY persisted check attempt — both terminal outcomes (approved / failed) and the non-terminal pending (wrong code, attempts remaining). Emitted before the conditional verification.approved / verification.failed dispatch, so subscribers see a consistent per-attempt stream. Twilio Verify verification_check.completed parity.

{
  "type": "verification.checked",
  "data": {
    "verification_id": "ver_abc123",
    "channel": "sms",
    "to": "+14155552671",
    "attempt_count": 1,
    "outcome": "pending",
    "checked_at": "2026-03-08T12:00:00Z"
  }
}

outcome is approved / pending / failed.

`verification.fallback_triggered`

The async fallback engine successfully advanced to a new channel. Dedup-guarded so a scheduler retry does not double-fire.

{
  "type": "verification.fallback_triggered",
  "data": {
    "verification_id": "ver_abc123",
    "channel": "voice",
    "channel_index": 1,
    "reason": "timeout"
  }
}

reason is timeout or delivery_failed.

`verification.fallback_exhausted`

The fallback engine tried every configured channel without obtaining a verified status. The verification row is set to failed before this fires. phone is masked (first five characters, then ****) and exhausted_at is the ISO 8601 timestamp at which the engine gave up.

{
  "type": "verification.fallback_exhausted",
  "data": {
    "verification_id": "ver_abc123",
    "phone": "+1415****",
    "channels_attempted": ["sms", "voice", "email"],
    "exhausted_at": "2026-07-02T18:04:11.000Z"
  }
}

Number Lifecycle & Port-Out Events

DID inventory, compliance, and port-out lifecycle webhooks. Tenant-scoped.

`number.updated`

Fires on every successful per-DID mutation. Suppressed for a no-op edit (an empty PUT that changes no caller-supplied field).

{
  "type": "number.updated",
  "data": {
    "number_id": "num_abc123",
    "phone_number": "+14155552671",
    "updated_fields": ["friendly_name", "tags"],
    "status": "active"
  }
}

`number.released_compliance_timeout`

A number was auto-released because its compliance deadline elapsed without the carrier activating it. The captured monthly cost is refunded to the tenant wallet. Distinct from the operator-initiated number.released so you can branch on a number lost to a missed deadline.

{
  "type": "number.released_compliance_timeout",
  "data": {
    "phone_number_id": "num_abc123",
    "phone_number": "+14155552671",
    "provider": "telnyx",
    "monthly_cost_cents": 100,
    "reason": "compliance_timeout",
    "released_at": "2026-03-08T12:00:00Z"
  }
}

`number.inventory.low`

A low-DID-inventory alert per (country_code, area_code_prefix) bucket whose available count fell below the threshold. Wire to a dashboard banner or auto-reprovision via the Numbers API before run-out.

{
  "type": "number.inventory.low",
  "data": {
    "country_code": "US",
    "area_code_prefix": "415",
    "available_count": 3,
    "threshold": 10,
    "raised_at": "2026-03-08T12:00:00Z"
  }
}

`porting.request.loa_signed`

A port-IN Letter of Authorization was signed in-platform — “ready to submit to carrier”. Carries the signer details so audit dashboards reconcile without an extra fetch.

{
  "type": "porting.request.loa_signed",
  "data": {
    "porting_request_id": "port_abc123",
    "signer_name": "Jordan Lee",
    "signer_email": "jordan@example.com",
    "signed_at": "2026-03-08T12:00:00Z"
  }
}

`number.port_out.requested` / `number.port_out.cancelled`

Outbound port lifecycle — a DID Orbit hosts is being moved to (or kept from leaving for) another carrier. Lets you reconcile downstream billing and contact lists when a DID leaves the platform.

{
  "type": "number.port_out.requested",
  "data": {
    "phone_number": "+14155552671",
    "provider": "telnyx",
    "requested_at": "2026-03-08T12:00:00Z"
  }
}

number.port_out.cancelled carries the same identifiers for an aborted port-out.

SIP Trunk Events

`sip_trunk.status_changed`

A customer SIP trunk’s registration state transitioned between registered and unregistered. Emitted by the register-poll reconciler only on a genuine edge — a still-down trunk re-probed unregistered does NOT fire, so a flapping registrar yields one event per real transition, not one per poll tick. Tenant-scoped.

{
  "type": "sip_trunk.status_changed",
  "data": {
    "trunk_id": "trunk_abc123",
    "name": "Acme PBX",
    "direction": "inbound",
    "status": "unregistered",
    "previous_status": "registered",
    "last_registration_error": "403 Forbidden",
    "last_registration_check_at": "2026-03-08T12:00:00Z",
    "organization_id": "org_abc"
  }
}

AI Agent Events

`agent.response`

Fires after an AI agent finalizes an LLM turn (both the synchronous request/response API and the SSE-stream API). Tenants subscribed to agent.response receive the same structured envelope the webhook tester documents. Best-effort — a delivery failure never blocks the API response. Tenant-scoped.

{
  "type": "agent.response",
  "data": {
    "agent_id": "agt_abc123",
    "conversation_id": "conv_abc123",
    "message_id": "msg_abc123",
    "response": "Your refund has been processed.",
    "tokens_used": 1758,
    "prompt_tokens": 1742,
    "completion_tokens": 16,
    "model": "claude-sonnet-4-5",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

tokens_used is the full billed turn, not just the visible reply. It counts the prompt context the model actually reads — your system prompt, tool definitions, retrieved knowledge-base passages, memory, and earlier turns in the conversation — plus the generated response. That context dominates the total, so tokens_used is normally far larger than the reply text suggests, and can exceed a naive character count of the response (tokenization is model-specific; non-Latin scripts cost roughly 2–3 tokens per character). It always reconciles as tokens_used === prompt_tokens + completion_tokens — in the example above, 1742 + 16 = 1758. Use the prompt_tokens / completion_tokens split to attribute spend between context and generation.

`agent.dnc.marked`

Fires when an AI voice / text agent invokes its mark_dnc tool and the platform persists the suppression. Wire into your CRM / consent-of-record system.

{
  "type": "agent.dnc.marked",
  "data": {
    "channel": "sms",
    "address": "+14155552671",
    "address_kind": "phone",
    "reason": "customer_request",
    "contact_id": "con_abc",
    "suppressed_voice_dnc": true,
    "conversation_id": "conv_abc123"
  }
}

Campaign Drip Events

`campaign.drip_step.sent`

Fires once per (contact, step) the moment a drip-step message is enqueued successfully. Companion to campaign.drip_step.completed, which fires once per step as the aggregate. Tenant-scoped.

{
  "type": "campaign.drip_step.sent",
  "data": {
    "campaign_id": "camp_abc123",
    "step_id": "step_abc123",
    "step_index": 2,
    "contact_id": "con_abc",
    "enrollment_id": "enr_abc123",
    "message_id": "msg_abc123",
    "channel": "sms",
    "sent_at": "2026-03-08T12:00:00Z"
  }
}

Billing Lifecycle Events

Stripe-driven billing webhooks fanned out to tenant subscribers. The Stripe envelope is deduplicated, so subscribers receive exactly one delivery per source event. Tenant-scoped.

`invoice.created`

A draft invoice was opened (cycle boundary, metered-usage threshold, or manual invoice).

{
  "type": "invoice.created",
  "data": {
    "organization_id": "org_abc",
    "invoice_id": "in_abc123",
    "amount_due_cents": 4200,
    "currency": "usd",
    "period_start": 1709856000,
    "period_end": 1712448000,
    "due_date": 1712448000,
    "hosted_invoice_url": "https://invoice.stripe.com/i/..."
  }
}

period_start, period_end, and due_date are Unix timestamps (or null).

`payment.failed`

A PaymentIntent failed (e.g. an auto-topup card decline). Distinct from an invoice payment failure — PI-driven failures originate from the recharge path and carry no invoice id. Wire into dunning / customer- service tooling.

{
  "type": "payment.failed",
  "data": {
    "organization_id": "org_abc",
    "payment_intent_id": "pi_abc123",
    "invoice_id": null,
    "amount_cents": 5000,
    "currency": "usd",
    "failure_code": "card_declined",
    "failure_message": "Your card was declined.",
    "failed_at": "2026-03-08T12:00:00Z",
    "retry_count": 0
  }
}

`subscription.updated`

A billing-subscription state change (e.g. scheduled cancellation, reactivation, plan change). Carries the action that drove the change.

{
  "type": "subscription.updated",
  "data": {
    "organization_id": "org_abc",
    "action": "reactivate"
  }
}

`credits.low`

Deprecated alias of balance.low. Prefer balance.low for new integrations.

WhatsApp Template & Call Lifecycle Events

`whatsapp.template.quality_update`

Meta reported a template quality-rating change. The Meta webhook value fields are spread into data alongside waba_id.

{
  "type": "whatsapp.template.quality_update",
  "data": {
    "waba_id": "1234567890",
    "message_template_id": "9876543210",
    "message_template_name": "order_update",
    "message_template_language": "en_US",
    "previous_quality_score": "GREEN",
    "new_quality_score": "YELLOW"
  }
}

`whatsapp.template.category_update`

Meta auto-recategorized a template between MARKETING / UTILITY / AUTHENTICATION. Orbit also re-syncs the local templates.category so cost tracking prices off Meta’s current category.

{
  "type": "whatsapp.template.category_update",
  "data": {
    "waba_id": "1234567890",
    "message_template_id": "9876543210",
    "message_template_name": "order_update",
    "message_template_language": "en_US",
    "previous_category": "MARKETING",
    "new_category": "UTILITY",
    "correct_category": "UTILITY"
  }
}

`whatsapp.template.components_update`

Meta auto-edited a template’s components for compliance (e.g. inserting the standard opt-out hint into a MARKETING body). Orbit re-syncs the local templates.content to Meta’s truth.

{
  "type": "whatsapp.template.components_update",
  "data": {
    "waba_id": "1234567890",
    "message_template_id": "9876543210",
    "message_template_name": "order_update",
    "message_template_language": "en_US"
  }
}

`whatsapp.call.accepted` / `whatsapp.call.terminated`

WhatsApp Business Calling lifecycle. Fan out alongside the legacy whatsapp.call.received event. Both carry the same payload shape; phase discriminates the lifecycle stage.

{
  "type": "whatsapp.call.accepted",
  "data": {
    "waba_id": "1234567890",
    "phone_number_id": "1098765432",
    "meta_call_id": "wacid.abc123",
    "wa_call_log_id": "wacall_abc123",
    "direction": "inbound",
    "from": "+14155552671",
    "to": "+14155550000",
    "phase": "accepted",
    "meta_event": "call",
    "meta_status": "ACCEPTED",
    "duration_seconds": null,
    "biz_opaque_callback_data": null
  }
}

whatsapp.call.terminated carries the same shape with phase: "terminated" and a populated duration_seconds.

Voice Eval Events

Voice-agent regression-suite lifecycle webhooks. Tenant-scoped.

`voice_eval.run_started` / `voice_eval.run_completed`

Fire when an eval run begins and finishes (pass or fail).

{
  "type": "voice_eval.run_completed",
  "data": {
    "run_id": "evalrun_abc123",
    "agent_id": "agt_abc123",
    "passed": 18,
    "failed": 2,
    "p95_latency_ms": 940,
    "regression_vs_baseline": true
  }
}

voice_eval.run_started carries { run_id, agent_id }.

`voice_eval.regression_detected`

Fires when P95 latency or judge score regresses beyond the threshold vs the baseline run.

{
  "type": "voice_eval.regression_detected",
  "data": {
    "run_id": "evalrun_abc123",
    "agent_id": "agt_abc123",
    "baseline_run_id": "evalrun_xyz789",
    "p95_regression_pct": 14.2,
    "judge_score_regression_pct": 6.8
  }
}

Subscribing to Events

curl -X POST https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/orbit",
    "events": ["message.delivered", "message.failed", "call.completed"],
    "secret": "whsec_your_secret"
  }'

Use "events": ["*"] to subscribe to all event types. Subscribing to a name not listed on this page returns a 422.

​Webhook Events Reference

​Event Envelope

​Catalog Index

​Message Events

​Contact Events

​Campaign Events

​Voice Events

​Agent Events

​Flow Events

​Verification Events

​Number / Porting Events

​Conversation Events

​Compliance Events

​List / Segment Events

​Webhook Endpoint Events

​Billing Events

​Commerce Events

​Channel Failover Events

​Push Events

​Number Masking (Proxy) Events

​WhatsApp Events

​Supervisor Events

​SIP Trunk Events

​CDP Events

​Other

​Message Events

​message.created

​message.sent

​message.delivered

​message.failed

​message.read

​message.received

​expired and submitted_no_receipt (delivered via message.failed)

​message.recipient_deactivated

​Contact Events

​contact.created

​contact.updated

​contact.deleted

​contact.merged

​contact.bulk_imported

​contact.opted_in / contact.opted_out

​contact.recertification_due

​contact.phone_changed

​contact.segment_changed

​Campaign Events

​campaign.created / campaign.updated / campaign.deleted

​campaign.started

​campaign.completed

​campaign.paused / campaign.resumed

​campaign.drip_step.completed

​campaign.drip.completed

​Voice Events

​call.initiated

​call.answered

​call.completed

​call.failed

​call.transferred

​call.dtmf_sent

​call.recording.paused / call.recording.resumed

​call.secure_payment.started / call.secure_payment.completed / call.secure_payment.cancelled

​call.recording.ready

​call.transcription.ready

​call.synthesis.ready (legacy inline pipeline)

​call.synthesized (post-call synthesis pipeline)

​call.ringing

​Conference Events

​conference.created

​conference.participant_joined

​conference.participant_left

​conference.ended

​Recording Events

​recording.started

​recording.completed

​recording.failed

​voicemail.received

​voicemail.transcript_updated

​recording.retention_deleted

​Agent Events

​agent.created / agent.updated / agent.deleted / agent.deployed

​agent.conversation.started

Webhook Events Reference

Event Envelope

Catalog Index

Message Events

Contact Events

Campaign Events

Voice Events

Agent Events

Flow Events

Verification Events

Number / Porting Events

Conversation Events

Compliance Events

List / Segment Events

Webhook Endpoint Events

Billing Events

Commerce Events

Channel Failover Events

Push Events

Number Masking (Proxy) Events

WhatsApp Events

Supervisor Events

SIP Trunk Events

CDP Events

Other

Message Events

`message.created`

`message.sent`

`message.delivered`

`message.failed`

`message.read`

`message.received`

`expired` and `submitted_no_receipt` (delivered via `message.failed`)

`message.recipient_deactivated`

Contact Events

`contact.created`

`contact.updated`

`contact.deleted`

`contact.merged`

`contact.bulk_imported`

`contact.opted_in` / `contact.opted_out`

`contact.recertification_due`

`contact.phone_changed`

`contact.segment_changed`

Campaign Events

`campaign.created` / `campaign.updated` / `campaign.deleted`

`campaign.started`

`campaign.completed`

`campaign.paused` / `campaign.resumed`

`campaign.drip_step.completed`

`campaign.drip.completed`

Voice Events

`call.initiated`

`call.answered`

`call.completed`

`call.failed`

`call.transferred`

`call.dtmf_sent`

`call.recording.paused` / `call.recording.resumed`

`call.secure_payment.started` / `call.secure_payment.completed` / `call.secure_payment.cancelled`

`call.recording.ready`

`call.transcription.ready`

`call.synthesis.ready` (legacy inline pipeline)

`call.synthesized` (post-call synthesis pipeline)

`call.ringing`

Conference Events

`conference.created`

`conference.participant_joined`

`conference.participant_left`

`conference.ended`

Recording Events

`recording.started`

`recording.completed`

`recording.failed`

`voicemail.received`

`voicemail.transcript_updated`

`recording.retention_deleted`

Agent Events

`agent.created` / `agent.updated` / `agent.deleted` / `agent.deployed`

`agent.conversation.started`