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.
- Extract a dedupe key from the payload (
data.call.callId,data.batch_id, etc.) - Before processing, check whether that key is already in your database
- If yes: return
204immediately - If no: process, then record the key atomically
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

