Webhooks

​

The four events

• call.completed does not mean the call connected. A busy line and a wrong number fire it too. Read the session status for state and failureReason before treating it as a conversation.
• No scorecard means no call.graded, ever. Grading rides the scorecard: assistant-level for direct calls, campaign-level for campaign calls.
• Emit order is fixed, arrival order is not. Events go out as completed, graded, conversion, callback, but each one retries independently. Don’t assume call.completed lands first.
• occurredAt is when the analysis ran, not when the call ended. For call timings, read the session’s timestamps.

​

What arrives

{
  "schemaVersion": "upliftai.call.v1",
  "eventType": "call.graded",
  "eventId": "3f1c8a02-9d44-4e1b-b0a7-2c5e6f8d1a90#call.graded",
  "assistantId": "01efae24-b353-4621-a85a-4a04cba97570",
  "occurredAt": "2026-08-21T12:00:00.000Z",
  "data": { "callId": "3f1c8a02-9d44-4e1b-b0a7-2c5e6f8d1a90", "score": 82 }
}

• eventId is your idempotency key. It is callId#eventType, and a retry can deliver the same event twice. Process once per eventId.
• campaignId appears only on campaign calls. On every other call the key is absent, not null.
• callId and sessionId are the same string today. Either is the id every session endpoint takes.
• The payload is thin on purpose. No transcript, no recording, no per-rule breakdown, no phone number. The event tells you when to look, and the session detail is where you look.

​

Subscribing

• Adding the webhook is the opt-in. Every webhook in the project receives every event for every call. There is no per-event filter.
• The URL must be HTTPS and publicly routable. Private, loopback, and link-local addresses are rejected at create time.
• To rotate the secret, add a webhook with the new one, then delete the old one.

​

Verifying the signature

x-uplift-ai-signature: t=1755772800,v1=6c0f0e8b1a…

import crypto from 'node:crypto'

function verify(rawBody, header, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]+)$/.exec(header)
  if (!m) return false
  const [, t, sig] = m
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  return expected.length === sig.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))
}

​

Delivery and retries

• Answer fast with any 2xx. The response body is ignored. The deadline is 10 seconds, so queue the work rather than doing it inline.
• Transient failures retry. Timeouts, network errors, 408, 429, and any 5xx are retried at 30 seconds, 5 minutes, and 30 minutes. Four attempts total.
• Any other 4xx does not retry. A 401 or 404 is a permanent failure and the delivery dies on the first attempt.
• Dead deliveries land in Delivery failures on the Webhooks page, with the status code, the reason, and the attempt count, kept for 90 days. There is no event for a failed delivery.

​

Testing from localhost

ngrok http 3000

• Free ngrok URLs change every restart. Claim ngrok’s free static domain, so the URL you saved keeps working.
• The tunnel is public. Keep the signature check on, even on your laptop.