Webhooks

Real-time events, pushed to you.

Subscribe an HTTPS endpoint and OneVox sends a signed JSON event the moment something happens — conversations, escalations, knowledge gaps and deployments.

<500ms

Median delivery time

Event types

72 hrs

Automatic retries with backoff

HMAC

SHA-256 signed payloads

Event types

Conversations

conversation.startedA caller or user starts a new conversation on any channel.

conversation.endedA conversation ends. Includes duration, outcome and transcript URL.

conversation.transcript.readyThe full transcript and summary are available.

Escalations

escalation.requestedThe agent decides a human is needed and requests a handoff.

escalation.acceptedA human teammate accepts the handoff.

Knowledge

knowledge.gap.detectedThe agent could not answer a question from its knowledge sources.

knowledge.source.syncedA website, file or integration finished syncing.

Agents

agent.publishedA new agent version is published to production.

agent.rolled_backAn agent is rolled back to a previous version.

Example payload

{
  "id": "evt_01J9ZK4Q7M3X",
  "type": "conversation.ended",
  "created": 1727222400,
  "data": {
    "conversation_id": "conv_8f2a91",
    "agent_id": "agt_aria",
    "channel": "voice",
    "duration_sec": 184,
    "outcome": "resolved",
    "csat_predicted": 4.7,
    "transcript_url": "https://api.onevox.ai/v1/conversations/conv_8f2a91/transcript"
  }
}

Verify signatures

Every request includes an onevox-signature header. Compute an HMAC-SHA256 of the raw body with your endpoint secret and compare.

import crypto from "node:crypto"

export function verify(req, secret) {
  const sig = req.headers["onevox-signature"]
  const expected = crypto
    .createHmac("sha256", secret)
    .update(req.rawBody)
    .digest("hex")
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
}

Delivery and retries

Respond with 2xx

Return any 2xx status within 10 seconds to acknowledge the event.

Automatic retries

Failed deliveries retry with exponential backoff for up to 72 hours.

Replay events

Re-send any event from the last 30 days from the dashboard or API.

Start receiving events

Add an endpoint in the dashboard or with POST /v1/webhooks.