DevelopersGuides
Webhooks
Webhooks send your server a signed JSON POST the moment something happens: a call ends, a message is taken, an appointment is booked, moved or canceled, or a new caller is added. They also work with Zapier, Make and n8n: paste their catch-hook URL as the endpoint.
On this page
Events
- call.completed
- A call ended. Includes the caller, the AI Employee, times, the summary and full transcript, the caller’s contact and any intake form answers.
- message.taken
- The AI Employee took a message: the caller’s name and number, the message and whether it’s urgent.
- appointment.booked
- An appointment was booked: on a call, on the booking page, by your team or through the API.
- appointment.rescheduled
- An appointment moved. Includes the previous start time.
- appointment.canceled
- An appointment was canceled, and by whom.
- lead.captured
- A first-time caller was added to your contacts.
GET /v1/events/types returns the same list, so your code can check for new types.
Adding an endpoint
In the dashboard
As the account owner, open Integrations, then the Webhooks & Zapier tab, and choose Add URL. Enter the URL, an optional label, and the events to send. The signing secret (
whsec_…) is shown when you add it; the owner can Reveal it again later.Or through the API
POST /v1/webhookswith thewebhooks:writescope. The response is the only time the API returns the secret. Partner keys can manage a client's endpoints with theAssistCall-Accountheader.curl https://api.assistcall.ai/v1/webhooks \ -H "Authorization: Bearer $ASSISTCALL_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/assistcall", "description": "CRM sync", "events": ["call.completed", "appointment.booked"] }'Send a test
Choose Send test in the dashboard, or call
POST /v1/webhooks/{id}/test. A sample event of the type you pick is sent once, signed like a real one, with"test": truein itsdata, and you see what your endpoint answered.
The URL must be https:// and publicly reachable: addresses in private, loopback or link-local ranges are refused, including names that resolve to them. Put credentials in your own checks, not in the URL. An account can have up to 10 endpoints.
Payload
Every event has the same envelope: an id (the same for every endpoint and every retry, so use it to skip duplicates), the type, when it happened, the account, and the event's data.
{
"id": "0b9a3f7e-5c21-4d8e-9f60-2a7c1e4b8d35",
"type": "call.completed",
"created_at": "2026-10-25T14:06:12.481Z",
"account": { "id": "5d0e6a8b-1f2c-4e3d-9a7b-6c5d4e3f2a1b", "name": "Demo Dental" },
"data": {
"call": {
"id": "c2f1d8e4-7a6b-4c5d-8e9f-0a1b2c3d4e5f",
"from": "+12125550147",
"to": "+12125550101",
"direction": "inbound",
"receptionist": "Mia",
"started_at": "2026-10-25T14:03:01.000Z",
"ended_at": "2026-10-25T14:06:05.000Z",
"duration_seconds": 184,
"summary": "Maria Lopez, a new patient, booked a cleaning and exam for Thursday at 10:00 AM.",
"transcript": "AI: Thanks for calling Demo Dental! This is Mia. How can I help you today?\nCaller: Hi, I'd like to book a cleaning. I'm a new patient.\n…",
"ended_reason": "customer-ended-call",
"recording_url": "https://app.assistcall.ai/calls/c2f1d8e4-7a6b-4c5d-8e9f-0a1b2c3d4e5f",
"url": "https://app.assistcall.ai/calls/c2f1d8e4-7a6b-4c5d-8e9f-0a1b2c3d4e5f"
},
"contact": { "id": "8e7d6c5b-4a39-4281-9f0e-1d2c3b4a5968", "name": "Maria Lopez", "phone": "+12125550147", "email": "" },
"forms": [
{ "form": "New patient", "test": false, "answers": { "Full name": "Maria Lopez", "Reason for visit": "Cleaning and exam" } }
]
}
}In call.completed, contact is null when the caller's number was hidden or isn't in your contacts, and forms lists the answers to any intake forms the AI Employee filled in (keyed by field label, with a Notes entry when there are notes; test marks the owner's own test calls). The url opens the call in the dashboard, where the recording is.
message.taken
"data": {
"message": {
"caller_name": "James Carter",
"caller_phone": "+17185550133",
"body": "Cracked tooth, pain when chewing. Wants an emergency visit as soon as possible.",
"urgency": "urgent"
},
"call": { "id": "a4b3c2d1-…", "url": "https://app.assistcall.ai/calls/a4b3c2d1-…" }
}urgency is "normal" or "urgent". call is null if the message didn’t come from a call.
appointment.booked
"data": {
"appointment": {
"id": "f1e2d3c4-…",
"name": "Maria Lopez",
"phone": "+12125550147",
"email": "[email protected]",
"starts_at": "2026-10-29T14:00:00.000Z",
"duration_min": 60,
"status": "scheduled",
"reason": "New patient cleaning and exam",
"notes": "",
"source": "ai",
"contact_id": "8e7d6c5b-…",
"call_id": "c2f1d8e4-…"
}
}source is "ai" (booked on a call), "booking" (your booking page) or "manual" (your team or the API). contact_id and call_id can be null.
appointment.rescheduled
"data": {
"appointment": { "id": "f1e2d3c4-…", "starts_at": "2026-10-31T19:00:00.000Z", "status": "scheduled", … },
"previous_starts_at": "2026-10-29T14:00:00.000Z"
}appointment has the same fields as in appointment.booked, with the new time.
appointment.canceled
"data": {
"appointment": { "id": "f1e2d3c4-…", "status": "canceled", … },
"canceled_by": "booker"
}canceled_by is "booker" (the customer, from their booking link), "ai" (on a call) or "business" (your team or the API).
lead.captured
"data": {
"contact": { "id": "8e7d6c5b-…", "name": "Maria Lopez", "phone": "+12125550147", "email": "" },
"source": "call"
}Request headers
- Content-Type
application/json- User-Agent
AssistCall-Connect/1.0- X-AssistCall-Event
- The event type, e.g.
call.completed. - X-AssistCall-Delivery
- The id of this delivery to this endpoint. Retries of it keep the same id.
- X-AssistCall-Timestamp
- When this attempt was sent, in Unix seconds. Part of the signature.
- X-AssistCall-Signature
v1=followed by the signature (64 hex characters).
Verifying signatures
Check every request before trusting it. The signature is a hex HMAC-SHA256 of the timestamp, a period, and the raw request body, keyed with the endpoint's signing secret (the whole whsec_… string):
signature = hex( HMAC-SHA256( key = signing secret, message = timestamp + "." + raw body ) )- Read
X-AssistCall-Timestampand reject it if it's more than 5 minutes from your clock (stops replays). - Compute the HMAC over the raw bytes of the body. Parsing the JSON and serializing it again changes spacing and escaping, and the signature won't match.
- Compare with the part of
X-AssistCall-Signatureafterv1=, in constant time.
import crypto from 'node:crypto';
import express from 'express';
const SECRET = process.env.ASSISTCALL_WEBHOOK_SECRET; // whsec_…, the endpoint's signing secret
/** True if the request is from AssistCall and was sent within the last 5 minutes. */
export function verify(rawBody, timestamp, signature, secret, toleranceSec = 300) {
if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSec) return false;
const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex');
const given = signature.startsWith('v1=') ? signature.slice(3) : '';
return given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
const app = express();
// express.raw keeps the exact bytes AssistCall signed; parsing and re-serializing the JSON would change them.
app.post('/webhooks/assistcall', express.raw({ type: 'application/json' }), async (req, res) => {
const ok = verify(req.body, req.get('X-AssistCall-Timestamp') ?? '', req.get('X-AssistCall-Signature') ?? '', SECRET);
if (!ok) return res.status(400).send('Invalid signature');
const event = JSON.parse(req.body.toString('utf8'));
if (await alreadyHandled(event.id)) return res.sendStatus(200); // deliveries can repeat
res.sendStatus(200); // answer within 10 seconds; do slow work after
await handle(event);
});Delivery and retries
- Answer with any 2xx status within 10 seconds. Do slow work after you've answered, or in a queue. The response body is ignored, and redirects aren't followed (a
3xxcounts as a failure). - Anything else is retried: a non-2xx status, a timeout or a connection error.
- Events are delivered in the background, usually within seconds.
| Attempt | When |
|---|---|
| 1 | Right away |
| 2 | 1 minute after the first failure |
| 3 | 5 minutes after that |
| 4 | 30 minutes after that |
| 5 | 2 hours after that |
| 6 (last) | 6 hours after that: about 8½ hours after the event |
After the sixth failed attempt the delivery is marked failed. You can see every delivery, its status and your endpoint's answer under Deliveries in the dashboard, and Resend any of them, for example after fixing a bug. Turning an endpoint off or removing it stops its pending retries.
Handling events well
- Expect duplicates. Store each event's
idand skip ones you've seen. - Don't rely on order. Retries can deliver an older event after a newer one. Use
created_at, or fetch the current state from the API (for exampleGET /v1/appointments/{id}) before acting. - Ignore what you don't know. New event types and new fields can appear (see Versioning).
- Check
data.testso test events don't create real records.
Changing the signing secret
An endpoint's secret is fixed. To replace it without missing events: add the same URL again (it gets a new secret), make your code accept either secret, then remove the old endpoint. While both exist each event arrives twice with the same id, which your duplicate check already handles.