Webhook Events

Orbit emits events across messaging, voice, agents, flows, contacts, billing, and account activity. Subscribe to specific events when registering a webhook, or pass ["*"] to receive everything.

This page is the canonical catalog — every event listed here is emitted by the platform and accepted by the subscription validator. For full payload examples, see the Webhook Events Reference.The list is generated from WEBHOOK_EVENT_TYPES in packages/shared/src/constants.ts; the same constant powers the server-side Zod enum that validates webhook_endpoints.events[], so any name not in this catalog cannot be subscribed to.

Message Events

Event	Description
`message.created`	Outbound message accepted and queued for delivery
`message.sent`	Message handed off to the carrier/provider
`message.delivered`	Message confirmed delivered to the recipient
`message.failed`	Message delivery failed (terminal)
`message.read`	Recipient marked the message as read (WhatsApp / RCS)
`message.received`	Inbound message received from a user

Contact Events

Event	Description
`contact.created`	A new contact was created
`contact.updated`	An existing contact was modified
`contact.deleted`	A contact was removed
`contact.merged`	Two contact rows merged into one
`contact.opted_in`	Recipient sent an opt-in keyword (e.g. START / UNSTOP)
`contact.opted_out`	Recipient sent an opt-out keyword (e.g. STOP)
`contact.recertification_due`	Annual RMD consent recertification window opened
`contact.segment_changed`	Predictive segment label transitioned (e.g. champion → at_risk)

Campaign Events

Event	Description
`campaign.created`	Campaign row created
`campaign.updated`	Campaign config edited
`campaign.deleted`	Campaign removed
`campaign.started`	Campaign execution began
`campaign.completed`	Campaign finished sending to all recipients
`campaign.paused`	Campaign manually paused
`campaign.resumed`	Paused campaign resumed
`campaign.drip_step.completed`	Single drip step finished sending to its slice
`campaign.drip.completed`	Entire drip campaign finished its full schedule

Voice Events

Event	Description
`call.ringing`	Inbound call invite received at the SIP edge, before answer
`call.initiated`	Outbound call placed (or first ringing event seen)
`call.answered`	Call was answered
`call.completed`	Call ended normally
`call.failed`	Call failed to connect (busy / no-answer / failed)
`call.transferred`	Active call transferred to another destination
`call.dtmf_sent`	Mid-call DTMF sequence injected via the API
`call.recording.paused`	SIPREC recording paused mid-call (e.g. PCI capture)
`call.recording.resumed`	SIPREC recording resumed after a pause
`call.recording.ready`	Recording uploaded to GCS and a download URL is available
`call.transcription.ready`	Transcript ready for the recording
`call.synthesis.ready`	Inline AI summary / sentiment ready (legacy path)
`call.synthesized`	Post-call synthesis pipeline emitted a structured summary
`recording.started`	A new recording began capture
`recording.completed`	Recording finalised (alias of `call.recording.ready` for call-scoped recordings; conference recordings use this name)
`recording.failed`	Recording attempt failed (storage write, codec mismatch, AMD aborted)
`recording.retention_deleted`	Recording about to be purged by retention policy (24h grace)
`conference.created`	Conference room created
`conference.participant_joined`	Participant successfully joined a conference
`conference.participant_left`	Participant disconnected (BYE, kicked, or conference ended)
`conference.ended`	Conference closed (last participant left, moderator ended, or max duration)
`voicemail.received`	A voicemail was recorded for an unanswered call
`voicemail.transcript_updated`	Late-arriving voicemail transcript recovered after retry

Trigger conditions, payload schemas, retry behaviour, and signature verification for every voice event are documented in the Webhook Events Reference. Voice events ride the same retry semantics as messaging events (exponential backoff: 1m, 5m, 15m, 1h, 6h — 5 attempts max). All deliveries carry the Devotel-Signature header — see Webhook Security for verification snippets.

Agent Events

Event	Description
`agent.created`	Agent created
`agent.updated`	Agent config / prompt / tools edited
`agent.deleted`	Agent removed
`agent.deployed`	Agent published to a channel / number
`agent.conversation.started`	Agent began a new conversation
`agent.conversation.ended`	Agent conversation closed
`agent.handoff.requested`	Agent escalated to a human operator
`agent.handoff_occurred`	Agent delegated to another specialist agent (`transfer_to_agent`)
`agent.calendar_event.created`	Agent’s `create_calendar_event` tool fired

Flow Events

Event	Description
`flow.created`	Flow draft created
`flow.updated`	Flow definition edited
`flow.published`	Flow published to a runnable state
`flow.deleted`	Flow removed
`flow.executed`	Coarse-grained execution result (always fires terminally)
`flow.execution.started`	Granular start signal at the beginning of a run
`flow.execution.completed`	Granular completion signal — ran to the terminal node
`flow.execution.failed`	Granular failure / timeout signal

Verification Events

Event	Description
`verification.sent`	Verification code sent (any channel)
`verification.approved`	Code verified successfully
`verification.failed`	Incorrect code, max attempts exceeded, or SIM-swap blocked

Number / Porting Events

Event	Description
`number.purchased`	New phone number acquired (or reclaimed from parking)
`number.released`	Number parked for release
`number.ported`	Port-in / port-out request created
`porting.request.cancelled`	Customer cancelled an in-flight port

Conversation Events

Event	Description
`conversation.created`	New conversation row created (e.g. journey-driven agent thread)

List / Segment Events

Event	Description
`list.created`	Static contact list created
`list.deleted`	Static contact list removed
`segment.created`	Dynamic / rule-based segment created
`segment.deleted`	Segment removed

Webhook Endpoint Events

Meta-events about webhook subscriptions themselves — useful for tenant admin audit pipelines.

Event	Description
`webhook_endpoint.created`	Endpoint registered
`webhook_endpoint.updated`	Endpoint URL / events / secret edited
`webhook_endpoint.deleted`	Endpoint removed

Billing Events

Event	Description
`balance.low`	Account balance dropped below the low-balance threshold
`balance.topped_up`	Stripe checkout completed and balance credited
`credits.purchased`	Deprecated — alias of `balance.topped_up`
`subscription.updated`	Stripe subscription state changed (cancelled / reactivated / plan change)

Channel Failover Events

Event	Description
`channel.failover`	A messaging channel failed over from one provider to its backup

Push Events

Event	Description
`push.delivered`	Mobile / web SDK acknowledged a push was rendered on-device
`push.opened`	User tapped the push and the SDK reported the open

Number Masking (Proxy) Events

Event	Description
`proxy.session.created`	Two-party proxy session created
`proxy.session.closed`	Proxy session closed (TTL expired or ended manually)
`proxy.message.forwarded`	Inbound to the proxy number was forwarded to the other participant

WhatsApp Events

These mirror Meta WABA webhook fields (field value in the Cloud API). Each fires after Orbit ingests the corresponding Meta callback.

WABA / business

Event	Description
`whatsapp.account.update`	Generic WABA settings change
`whatsapp.account.banned`	WABA banned by Meta
`whatsapp.account.restricted`	WABA restricted (sending limit / category)
`whatsapp.account.alert`	Operational alert (policy violation, payment failure)
`whatsapp.account.review_update`	Account review status changed
`whatsapp.account.settings_update`	WABA settings (profile / commerce) updated
`whatsapp.business.status_update`	Verification badge / official-account flag changed

Phone numbers

Event	Description
`whatsapp.phone.quality_update`	Per-phone quality rating changed
`whatsapp.phone.name_update`	Display name change pending or applied
`whatsapp.capability.update`	Channel capability flag updated
`whatsapp.security.alert`	Security event (password reset, login alert)
`whatsapp.flow.status_change`	WA Flow status transitioned
`whatsapp.quality.changed`	WABA-level quality score change

Templates

Event	Description
`whatsapp.template.approved`	Template approved by Meta review
`whatsapp.template.rejected`	Template rejected; `details.reason` carries Meta’s text
`whatsapp.template.quality_update`	Template quality rating changed
`whatsapp.template.category_update`	Template category (MARKETING / UTILITY / AUTH) changed
`whatsapp.template.components_update`	Meta auto-edited template components for compliance
`whatsapp.template.correct_category_detection`	Meta detected mismatch between intent and category

WhatsApp Business Calling

Event	Description
`whatsapp.call.received`	Legacy event — fired for every call lifecycle transition (BAU consumers)
`whatsapp.call.connected`	Call leg connected (Meta `event=connect` or `RINGING`)
`whatsapp.call.accepted`	Callee accepted, media path live (Meta `status=ACCEPTED`)
`whatsapp.call.terminated`	Call ended; status mapped to completed / missed / failed
`whatsapp.call.permission_granted`	Call permission granted (reply-button / 24h window / explicit consent)
`whatsapp.call.permission_revoked`	Permission revoked via in-app toggle

User / data subject

Event	Description
`whatsapp.user.preferences`	User toggled marketing / call preferences
`whatsapp.data.export_request`	GDPR Article 15 — user requested a data export
`whatsapp.data.delete_request`	GDPR Article 17 — user requested erasure

v25 webhook fields

Event	Description
`whatsapp.automatic_events`	Meta-detected business events (cart abandoned, etc.)
`whatsapp.group.lifecycle_update`	WA Group created / deleted
`whatsapp.group.participants_update`	Participants joined / left
`whatsapp.group.settings_update`	Group renamed / description edited
`whatsapp.group.status_update`	Group activated / archived
`whatsapp.history`	Initial-connection backfill of historical messages
`whatsapp.partner_solutions`	Partner integration events
`whatsapp.payment_configuration_update`	WA Pay setup state changed
`whatsapp.smb.app_state_sync`	SMB app state sync events
`whatsapp.smb.message_echoes`	Echoes of messages sent from the SMB app
`whatsapp.tracking_events`	Per-message tracking (link clicks, etc.)

Subscribing to Events

When creating a webhook, specify which events to receive:

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

Use "events": ["*"] to subscribe to all event types. Subscribing to a name not in the catalog above returns a 422.

Documentation Index

​Webhook Events

​Message Events

​Contact Events

​Campaign Events

​Voice Events

​Agent Events

​Flow Events

​Verification Events

​Number / Porting Events

​Conversation Events

​List / Segment Events

​Webhook Endpoint Events

​Billing Events

​Channel Failover Events

​Push Events

​Number Masking (Proxy) Events

​WhatsApp Events

​WABA / business

​Phone numbers

​Templates

​WhatsApp Business Calling

​User / data subject

​v25 webhook fields

​Subscribing to Events

​See also

Webhook Events

Message Events

Contact Events

Campaign Events

Voice Events

Agent Events

Flow Events

Verification Events

Number / Porting Events

Conversation Events

List / Segment Events

Webhook Endpoint Events

Billing Events

Channel Failover Events

Push Events

Number Masking (Proxy) Events

WhatsApp Events

WABA / business

Phone numbers

Templates

WhatsApp Business Calling

User / data subject

v25 webhook fields

Subscribing to Events

See also