Webhooks

Overview

Webhooks let your backend receive push notifications when key actions happen on your account — a call ends, a dubbing job completes, a workflow runs, and so on. Indigenius sends an HTTP POST to your configured endpoint with a JSON payload describing the event. Configure your webhook URL when creating an API key (callbackUrl) or when creating a workflow (webhook.url).

Configuring your webhook URL

Call lifecycle events are delivered to the callbackUrl configured on the API key that placed the call (POST /v1/webhooks or the callbackUrl field when creating a key). If that key has no callbackUrl configured, no delivery is attempted — the call still proceeds normally, it just won’t trigger webhooks.

Verifying the signature

Every delivery includes these headers:

Header	Description
`X-Indigenius-Signature`	HMAC-SHA256 of `{timestamp}.{body}`, signed with your key’s signing secret.
`X-Indigenius-Timestamp`	Millisecond timestamp used in the signature.
`X-Indigenius-Event`	The event type, matching the `event` field in the body.

Recompute the signature on your end and compare it (constant-time) against X-Indigenius-Signature before trusting the payload.

Delivery model

Events are delivered via HTTP POST to your endpoint.
Your endpoint must return a 2xx status code within 10 seconds. If it times out or returns a non-2xx, delivery is retried with backoff.
Process events asynchronously — do your actual work in a background job, not in the request handler.

Event payload shape

Every webhook delivery shares the same outer envelope:

{
  "event": "call.completed",
  "timestamp": "2026-06-05T14:32:00.000Z",
  "organizationId": "665e4a34c65bb95f2f2d72e0",
  "data": {}
}

Field	Type	Description
`event`	`string`	The event type (see table below).
`timestamp`	`ISO 8601 string`	When the event was emitted.
`organizationId`	`string`	Your organization ID.
`data`	`object`	Event-specific payload.

Event types

Call lifecycle events

Fired only for calls placed through a developer API key (a callbackUrl must also be configured on that key — see Configuring your webhook URL). Calls placed from the dashboard, or scheduled/batch calls, do not fire these. Phone calls can fire all of the events below. Web/widget calls only fire call.initiated, call.completed, and call.failed.

Event	Fired when
`call.initiated`	Outbound call started, or an inbound call was received.
`call.ringing`	Call is ringing at the recipient/agent.
`call.answered`	Call was connected and answered.
`call.completed`	Call ended successfully.
`call.failed`	Call disconnected or failed to connect.
`call.forwarded`	Call was routed to a forwarding destination.
`call.not_answered`	Call timed out with no answer.
`call.agent_busy`	The agent/line was busy.
`call.agent_unavailable`	No agent was available to take the call.
`call.announcement_completed`	An announcer call finished playing its announcement.

{
  "event": "call.completed",
  "timestamp": "2026-06-05T14:32:00.000Z",
  "organizationId": "665e4a34c65bb95f2f2d72e0",
  "data": {
    "callId": "665e4a34c65bb95f2f2d72e1",
    "assistantId": "665e4a34c65bb95f2f2d72e2",
    "type": "web",
    "status": "completed",
    "durationSeconds": 142
  }
}

Field	Type	Description
`data.callId`	`string`	Your call’s id — use it to look up full call details or transcripts.
`data.assistantId`	`string`	The assistant used on the call.
`data.type`	`string`	`phone`, `web`, or `widget`.
`data.status`	`string`	A short status word for the event (e.g. `ringing`, `busy`).
`data.durationSeconds`	`number`	Call duration in seconds. Only present on `call.completed`.

Webhook delivery outcome

Every delivery attempt — whether the customer endpoint accepted it or not — is logged and visible in Webhook History. A 2xx response is a Webhook Received outcome; anything else (including a timeout) is a Webhook Failed outcome, shown alongside the HTTP response code. These outcomes are not delivered as separate webhook calls — they describe the delivery of the event above, in the same history record.

`workflow.completed`

Fired when a workflow execution finishes successfully.

{
  "event": "workflow.completed",
  "timestamp": "2026-06-05T14:35:00.000Z",
  "organizationId": "665e4a34c65bb95f2f2d72e0",
  "data": {
    "workflowId": "665e4a34c65bb95f2f2d72e3",
    "jobId": "job_01hxyz",
    "status": "completed"
  }
}

`dubbing.completed`

Fired when a dubbing job finishes and media is ready to download.

{
  "event": "dubbing.completed",
  "timestamp": "2026-06-05T14:40:00.000Z",
  "organizationId": "665e4a34c65bb95f2f2d72e0",
  "data": {
    "dubbingId": "665e4a34c65bb95f2f2d72e7",
    "projectName": "Product explainer dub",
    "targetLanguage": "French",
    "status": "completed"
  }
}

`dubbing.failed`

Fired when a dubbing job fails during processing.

{
  "event": "dubbing.failed",
  "timestamp": "2026-06-05T14:40:00.000Z",
  "organizationId": "665e4a34c65bb95f2f2d72e0",
  "data": {
    "dubbingId": "665e4a34c65bb95f2f2d72e7",
    "reason": "source_video_unreachable"
  }
}

`tts.completed`

Fired when a text-to-speech job finishes.

{
  "event": "tts.completed",
  "timestamp": "2026-06-05T14:38:00.000Z",
  "organizationId": "665e4a34c65bb95f2f2d72e0",
  "data": {
    "jobId": "665e4a34c65bb95f2f2d72e8",
    "status": "completed"
  }
}

Receiver checklist

Use HTTPS

Indigenius only delivers to https:// endpoints. Plain HTTP URLs are rejected.

Respond quickly

Return 200 OK (or any 2xx) as soon as you receive and validate the payload. Do not block the response while processing.

Make handlers idempotent

Deliveries can be retried. Always check whether you have already processed an event before acting on it — use data.callId or data.jobId as your deduplication key.

Log event IDs

Log the event type, timestamp, and relevant IDs on every delivery. This makes it easy to cross-reference against Webhook History.

Example receiver (Node/Express)

import express from 'express';

const app = express();
app.use(express.json());

app.post('/hooks/indigenius', (req, res) => {
  // Acknowledge immediately
  res.sendStatus(200);

  // Process asynchronously
  const { event, data } = req.body;
  processEvent(event, data).catch(console.error);
});

async function processEvent(event, data) {
  switch (event) {
    case 'call.completed':
      await handleCallCompleted(data);
      break;
    case 'dubbing.completed':
      await handleDubbingCompleted(data);
      break;
    default:
      console.log('Unhandled event type:', event);
  }
}

Retry behaviour

If your endpoint returns a non-2xx status or times out, Indigenius retries delivery with exponential backoff. You can inspect all delivery attempts — successful and failed — in Webhook History.

Getting Started

Core APIs

Platform APIs

Overview

Configuring your webhook URL

Verifying the signature

Delivery model

Event payload shape

Event types

Call lifecycle events

Webhook delivery outcome

`workflow.completed`

`dubbing.completed`

`dubbing.failed`

`tts.completed`

Receiver checklist

Example receiver (Node/Express)

Retry behaviour

​Overview

​Configuring your webhook URL

​Verifying the signature

​Delivery model

​Event payload shape

​Event types

​Call lifecycle events

​Webhook delivery outcome

​workflow.completed

​dubbing.completed

​dubbing.failed

​tts.completed

​Receiver checklist

​Example receiver (Node/Express)

​Retry behaviour

Overview

Configuring your webhook URL

Verifying the signature

Delivery model

Event payload shape

Event types

Call lifecycle events

Webhook delivery outcome

`workflow.completed`

`dubbing.completed`

`dubbing.failed`

`tts.completed`

Receiver checklist

Example receiver (Node/Express)

Retry behaviour