Skip to main content

Webhooks Overview

Webhooks let Truedy push events to your server in real time when important things happen — a call ends, a batch campaign completes, a voice clone finishes training. Instead of polling the API every few seconds, your server gets notified the moment the event occurs.

When to use webhooks

Without webhooks you’d need to poll the API constantly — webhooks are more reliable, cheaper, and real-time.

How it works

1

You create a webhook endpoint in your app

A publicly accessible HTTPS URL that accepts POST requests with a JSON body.
2

You register the endpoint in Truedy

Dashboard → Settings → Webhooks → Add Endpoint. Paste your URL and choose which event types to receive.
3

An event occurs

A call ends, a campaign completes, etc.
4

Truedy dispatches the event

Truedy bundles the event data, signs it with HMAC-SHA256, and sends an HTTP POST to your URL.
5

Your server processes the event

Verify the signature, extract the event type and data, run your business logic.
6

Return 204 quickly

Truedy expects a 2xx response. If it doesn’t receive one within the timeout window, it may re-deliver the event. Return 204 immediately — process asynchronously if needed.

Minimal working receiver

Here is a minimal webhook handler to get you started:

Event payload structure

Every event Truedy sends has this envelope:
See Available Webhooks for the full catalogue of event types and their payload shapes.

Reliability guarantees

Truedy delivers webhooks at-least-once. Your receiver must be idempotent — the same event may arrive more than once if a delivery fails or times out.
To handle duplicates safely:
  1. Extract a dedupe key from the payload (data.call.callId, data.batch_id, etc.)
  2. Before processing, check whether that key is already in your database
  3. If yes: return 204 immediately
  4. If no: process, then record the key atomically
Full runbook in Webhook Error Handling & Retries.

Event families

Next steps

Available Webhooks

Complete event catalogue with payload shapes

Securing Webhooks

Node.js, Python & Flask HMAC verification examples

Error Handling & Retries

Idempotent receiver implementation with DB example

Idempotency

Platform-wide idempotency patterns