Inbound event ingest

Push events from your CRM, helpdesk, or e-commerce platform into a Voxy workspace. Each event can create a contact or lead, enroll the contact in a campaign, auto-originate a callback, and fan out to your notification channels — all configured per source in Workspace → Integrations.

Authentication

Every ingest request is verified two ways:

1. An API key carrying the events:write scope, sent as Authorization: Bearer voxy_sk_….
2. A per-source HMAC over the raw request body in the x-voxy-signature header (the signing secret is shown once when you create the source). See signature verification.

Unknown or disabled sources return 403 without revealing whether the source exists.

Event envelope

The body is a JSON envelope. externalEventId is your stable id (used for dedupe); type is your own label (optionally restricted via allowedEventTypes); contact and data are optional.

Event types

A source accepts any type unless you restrict its allowedEventTypes. These are common labels — the actions that run are configured per source, not selected by the type value:

Sending an event

Sign the exact bytes you send, then POST them:

A successful ingest returns the accepted event and what it triggered:

Idempotency

Ingest is idempotent on (workspace, source, externalEventId). Replaying the same externalEventId returns the original result without re-running the actions — safe to retry on a network error. See Idempotency.

Action pipeline

Each source maps accepted events to actions: create / upsert a contact, create a lead, enroll in a campaign, auto-originate a call from a chosen agent, and notify your channels. An auto-originated call always carries an agentId — Voxy never places an un-attributed call.