Ingestion/Webhooks

Webhook Ingestion

Secure multi-tenant webhooks for production call lifecycle, media, transcript, tools, handoffs and errors.

Tenant authentication

HMAC signature

Replay protection

Idempotency keys

Schema validation

Timestamp validation

Event versioning

Dead-letter queue

Rate limiting

Delivery audit logs

Endpoint

POST /api/v1/webhooks/ingest

Authorization: Bearer zh_live_demo
X-Ziply-Timestamp: <unix_sec>
X-Ziply-Signature: <hex hmac-sha256 of "${ts}.${rawBody}">
X-Ziply-Provider: vapi|livekit|twilio|...

Body: { type, version, idempotency_key, occurred_at, call, data }

Demo credentials

API key: zh_live_demo

Secret: whsec_demo_ziplyhuman_change_me

Event type

Security controls

Tenant auth: Bearer API key maps to organization + webhook secret.

HMAC:signature = HMAC-SHA256(secret, timestamp + "." + rawBody).

Replay protection: timestamps outside ±5 minutes rejected.

Idempotency: same key returns prior result without reprocessing.

Schema: type versioning (2026-01-01); invalid payloads → dead letter.

Rate limit: 120 req/min per tenant (demo in-memory).

Retries: clients should retry 429/5xx with backoff; DLQ holds permanent failures.

Event catalog (20 types)

call.started

Ingest call started from production agents

call.ringing

Ingest call ringing from production agents

call.answered

Ingest call answered from production agents

call.ended

Ingest call ended from production agents

call.transferred

Ingest call transferred from production agents

call.failed

Ingest call failed from production agents

audio.stream.started

Ingest audio stream started from production agents

audio.stream.stopped

Ingest audio stream stopped from production agents

transcript.partial

Ingest transcript partial from production agents

transcript.final

Ingest transcript final from production agents

agent.response.generated

Ingest agent response generated from production agents

tool.call.started

Ingest tool call started from production agents

tool.call.completed

Ingest tool call completed from production agents

tool.call.failed

Ingest tool call failed from production agents

workflow.state.changed

Ingest workflow state changed from production agents

handoff.initiated

Ingest handoff initiated from production agents

handoff.completed

Ingest handoff completed from production agents

recording.available

Ingest recording available from production agents

customer.feedback.submitted

Ingest customer feedback submitted from production agents

provider.error.received

Ingest provider error received from production agents

Delivery audit log

Time	Event	Status	HTTP	ms

No deliveries yet — send a signed test event.

Dead-letter queue

DLQ empty.