Post-call webhooks

Each agent can send signed JSON events to one HTTPS address when its calls end. Events carry the transcript, summary, analysis and recording links. For a step-by-step setup, see Receive post-call webhooks.

Every route here needs a key with write permission, including the read routes. A key with only read permission gets 403 FORBIDDEN, because saved addresses can hold tokens and aren't masked.

A missing or invalid key returns 401. :id must be the agent's UUID, or the route returns 400. An agent in another account returns 404.

A body or :id that fails validation returns 400 with the code VALIDATION_ERROR, and details.issues lists the problems. A rejected address or unavailable delivery returns the same code with the reason in error. See Errors.

The webhook settings object

The delivery receipt object

A receipt records what happened to one event. It holds metadata only, never the transcript, your endpoint's response or the address. Receipts are removed after 30 days.

curl https://backend.synthesys.app/api/v1/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/post-call-webhook \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "deliveryAvailable": true,
    "config": {
      "url": "https://example.com/webhooks/synthesys",
      "enabled": true,
      "version": "5d0c7b1e-2f64-4a39-b8e7-1c9a6f3d2e80",
      "hasSigningSecret": true,
      "updatedAt": "2026-10-30T12:00:00+00:00"
    },
    "deliveries": [
      {
        "id": "e7a1c2d4-6b3f-4e58-9a07-3d1f8c5b6a29",
        "call_id": "b1f4d8a3-7c2e-4d96-8e15-0a6c3f9b2d47",
        "event_type": "call.completed",
        "status": "delivered",
        "attempts": 1,
        "last_http_status": 200,
        "last_error": null,
        "created_at": "2026-10-31T12:00:05+00:00",
        "delivered_at": "2026-10-31T12:00:07+00:00"
      }
    ]
  }
}

curl -X PUT https://backend.synthesys.app/api/v1/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/post-call-webhook \
  -H "SYNTH_API_KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhooks/synthesys", "enabled": true, "expectedVersion": null}'

{
  "success": true,
  "data": {
    "deliveryAvailable": true,
    "config": {
      "url": "https://example.com/webhooks/synthesys",
      "enabled": true,
      "version": "5d0c7b1e-2f64-4a39-b8e7-1c9a6f3d2e80",
      "hasSigningSecret": true,
      "updatedAt": "2026-10-30T12:00:00+00:00"
    },
    "deliveries": []
  }
}

{
  "success": false,
  "error": "Settings changed. Reload before saving.",
  "code": "CONFLICT",
  "requestId": "0f6b2c9e-1d47-4a83-b5e2-7c3a9d1f4e60",
  "timestamp": "2026-10-31T12:00:00.000Z"
}

curl https://backend.synthesys.app/api/v1/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/post-call-webhook/deliveries \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "deliveryAvailable": true,
    "deliveries": [
      {
        "id": "a2c9e4f1-5d38-4b76-8f02-6e1b7d3c9a58",
        "call_id": "b1f4d8a3-7c2e-4d96-8e15-0a6c3f9b2d47",
        "event_type": "call.recording_ready",
        "status": "pending",
        "attempts": 2,
        "last_http_status": 503,
        "last_error": "Endpoint returned HTTP 503",
        "created_at": "2026-10-31T12:03:00+00:00",
        "delivered_at": null
      }
    ]
  }
}

curl -X POST https://backend.synthesys.app/api/v1/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/post-call-webhook/test \
  -H "SYNTH_API_KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedVersion": "5d0c7b1e-2f64-4a39-b8e7-1c9a6f3d2e80"}'

{
  "success": true,
  "data": { "deliveryId": "d4b8f1a6-3e92-4c57-a0d1-8f2e6b7c9a13" }
}

Event types

An event is sent for a call with this agent once the call's status is ended or failed, including test calls. The webhook must be enabled, and the call must have ended after the settings last changed. Calls older than 30 days don't produce events.

A recording that is ready before call.completed is sent is included in it. A call that never gets a transcript, such as an unanswered call, still sends call.completed after the wait. Its transcript and endedAt can be null.

Every event carries a full snapshot of the call, not a change list. Events can arrive late or out of order, so use createdAt to find the newest snapshot.

Event payload

Every event is a POST with a JSON body. Values that aren't available are null.

{
  "id": "e7a1c2d4-6b3f-4e58-9a07-3d1f8c5b6a29",
  "type": "call.completed",
  "version": 1,
  "createdAt": "2026-10-31T12:00:05.123456+00:00",
  "test": false,
  "call": {
    "id": "b1f4d8a3-7c2e-4d96-8e15-0a6c3f9b2d47",
    "agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "ended",
    "direction": "outbound",
    "type": "outboundPhoneCall",
    "isTestCall": false,
    "customerPhone": "+12025550123",
    "startedAt": "2026-10-31T11:57:30+00:00",
    "endedAt": "2026-10-31T12:00:02+00:00",
    "durationSeconds": 152,
    "endedReason": "customer-ended-call",
    "transcript": "AI: Hello, this is Sarah.\nUser: Hi Sarah.",
    "summary": "The customer booked a demo for Tuesday.",
    "analysis": { "successEvaluation": "true" },
    "recordings": [
      {
        "id": "f3a7c1e9-2b64-4d08-b5f1-9c8e7d6a3b12",
        "url": "https://example.com/signed/recording.mp3",
        "expiresAt": "2026-10-31T13:00:07.000Z"
      }
    ]
  }
}

The webhook.test body has test: true. Its call has direction set to outbound, type and endedReason set to test, isTestCall set to true, a 30-second duration, a null customerPhone and no recordings.

Value mapping

call.type and call.endedReason never name a specific voice or phone company. Any part of a value that would do so uses the word provider instead, so a failed connection can read provider-failed-to-connect-call. Other values, such as customer-ended-call, are unchanged.

Call logs and recordings use the same values, so you can compare them directly.

Request headers

Verify the signature

Compute an HMAC-SHA256 over {timestamp}.{rawRequestBody}. Use your full signing secret as the key, including its whsec_ prefix. Verify the raw bytes before parsing the JSON. Use a constant-time comparison, and reject timestamps more than five minutes old.

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody is the request body as received, before JSON parsing.
export function verifyWebhook(rawBody, timestamp, signature, secret) {
  if (!timestamp || !signature) return false;
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!(age <= 300)) return false;

  const digest = createHmac('sha256', secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest('hex');
  const expected = Buffer.from(`v1=${digest}`);
  const received = Buffer.from(signature);
  return expected.length === received.length && timingSafeEqual(expected, received);
}

Retries

Return a 2xx status within 10 seconds. An event is sent up to five times in total. Retries use exponential backoff with jitter, and the delay between attempts is capped at about 15 minutes. If the fifth send fails, the event is marked failed.

Delivery is at least once, so your endpoint can receive the same event twice. Remove duplicates by id, and record an event as processed only after you have applied it. The event's id and call snapshot stay the same on retries. The timestamp, signature and recording links are refreshed.

Before each attempt, the current settings are checked. If they changed, or the webhook was disabled, a pending event is marked canceled and isn't sent. webhook.test events still send while disabled.

There is no route to resend an event. Use Call logs to fetch results you missed.

Delivery errors

These are the values you can see in last_error.