Webhooks
A webhook is a message ListenFox sends to your server when something happens: a call is analyzed, a lead turns hot, a follow-up is due. Your system reacts straight away, without asking us every few minutes.
How webhooks work
- You give us a public https address on your server (an endpoint) and choose the events you want.
- We give you a secret for that endpoint. Store it; it’s shown once.
- When an event happens, we POST it to your address as JSON, signed with the secret. Your server checks the signature, answers with a 2xx status, and does its work.
Add an endpoint
In ListenFox, open Settings → Webhooks, click Add endpoint, paste the address and pick events. Or create one with the API, which is what n8n, Zapier and Make do for you:
curl -X POST "https://listenfox.com/api/public/v1/webhooks" \
-H "Authorization: Bearer $LISTENFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/hooks/listenfox", "events": ["call.analyzed", "lead.hot"]}'The answer includes secret, once. Use ["*"] to get every event. The key needs the webhooks scope, and must belong to a workspace admin. The address must be public: we don’t send to localhost or private networks, and we check that both when you add it and before every delivery. A workspace can have up to 20 endpoints. Step by step in the app
Events
Every event has the same envelope: id, type, created_at, workspace_id and data. The objects in data are the same as the API’s, so you rarely need a second request. When part of an event was written by AI reading a call (a summary, a score), the event carries "ai_generated": true.
| Event | When it’s sent |
|---|---|
call.created | A call arrived. |
call.analyzed | A call's analysis finished (the call without its transcript). |
call.failed | A call could not be analyzed. |
lead.hot | A contact became a hot lead for the first time. |
followup.created | A follow-up was created. |
followup.due | A follow-up is due today. |
trigger.fired | One of your triggers matched a call. |
order.matched | A store order was matched to a call. |
brief.ready | The daily brief is ready. |
call.created example
{
"id": "evt_sample",
"type": "call.created",
"created_at": "2026-10-19T13:01:15Z",
"workspace_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"data": {
"id": "00000000-0000-4000-8000-000000000001",
"started_at": "2026-10-19T12:49:15Z",
"duration_s": 248,
"direction": "inbound",
"caller_phone": "+15125550142",
"caller_name": "Maria Lopez",
"contact_id": "00000000-0000-4000-8000-000000000002",
"source": {
"id": "00000000-0000-4000-8000-000000000003",
"type": "ringba",
"name": "Ringba"
},
"campaign": "Spring promo",
"status": "pending",
"category": null,
"outcome": "open",
"lead_score": null,
"lead_band": null,
"summary": null,
"labels": [],
"followup_due": null,
"ordered": null,
"app_url": "https://listenfox.com/w/acme/calls/00000000-0000-4000-8000-000000000001",
"created_at": "2026-10-19T12:50:15Z",
"updated_at": "2026-10-19T12:53:15Z"
}
}call.analyzed example
{
"id": "evt_sample",
"type": "call.analyzed",
"created_at": "2026-10-19T13:01:15Z",
"workspace_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"data": {
"id": "00000000-0000-4000-8000-000000000001",
"started_at": "2026-10-19T12:49:15Z",
"duration_s": 248,
"direction": "inbound",
"caller_phone": "+15125550142",
"caller_name": "Maria Lopez",
"contact_id": "00000000-0000-4000-8000-000000000002",
"source": {
"id": "00000000-0000-4000-8000-000000000003",
"type": "ringba",
"name": "Ringba"
},
"campaign": "Spring promo",
"status": "analyzed",
"category": "booked",
"outcome": "open",
"lead_score": 86,
"lead_band": "hot",
"summary": "Maria asked about pricing for a kitchen remodel and booked a consultation for Thursday.",
"labels": [],
"followup_due": "2026-10-20T00:00:00Z",
"ordered": null,
"app_url": "https://listenfox.com/w/acme/calls/00000000-0000-4000-8000-000000000001",
"created_at": "2026-10-19T12:50:15Z",
"updated_at": "2026-10-19T12:53:15Z",
"key_moments": [
{
"label": "price_asked",
"start_s": 42.5,
"quote": "How much would a full remodel run?"
}
],
"answers": {},
"objections": [
"Price"
],
"questions": null,
"followups": [
{
"id": "00000000-0000-4000-8000-000000000004",
"title": "Confirm Thursday's consultation",
"due_at": "2026-10-20T00:00:00Z",
"status": "open",
"call_id": "00000000-0000-4000-8000-000000000001",
"contact_id": "00000000-0000-4000-8000-000000000002",
"assignee": null,
"app_url": "https://listenfox.com/w/acme/calls/00000000-0000-4000-8000-000000000001",
"created_at": "2026-10-19T12:53:15Z"
}
],
"orders": [],
"ai_generated": true
}
}call.failed example
{
"id": "evt_sample",
"type": "call.failed",
"created_at": "2026-10-19T13:01:15Z",
"workspace_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"data": {
"id": "00000000-0000-4000-8000-000000000001",
"started_at": "2026-10-19T12:49:15Z",
"duration_s": 248,
"direction": "inbound",
"caller_phone": "+15125550142",
"caller_name": "Maria Lopez",
"contact_id": "00000000-0000-4000-8000-000000000002",
"source": {
"id": "00000000-0000-4000-8000-000000000003",
"type": "ringba",
"name": "Ringba"
},
"campaign": "Spring promo",
"status": "failed",
"category": null,
"outcome": "open",
"lead_score": null,
"lead_band": null,
"summary": null,
"labels": [],
"followup_due": "2026-10-20T00:00:00Z",
"ordered": null,
"app_url": "https://listenfox.com/w/acme/calls/00000000-0000-4000-8000-000000000001",
"created_at": "2026-10-19T12:50:15Z",
"updated_at": "2026-10-19T12:53:15Z",
"reason": "audio_expired"
}
}lead.hot example
{
"id": "evt_sample",
"type": "lead.hot",
"created_at": "2026-10-19T13:01:15Z",
"workspace_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"data": {
"id": "00000000-0000-4000-8000-000000000002",
"name": "Maria Lopez",
"phone": "+15125550142",
"email": null,
"status": null,
"lead_score": 86,
"lead_band": "hot",
"last_call_at": "2026-10-19T12:49:15Z",
"calls_count": 2,
"custom_fields": {},
"app_url": "https://listenfox.com/w/acme/contacts/00000000-0000-4000-8000-000000000002",
"lead_card": {
"summary": "Maria asked about pricing for a kitchen remodel and booked a consultation for Thursday.",
"needs": [
"Kitchen remodel"
],
"objections": [
"Price"
],
"next_step": "Confirm Thursday's consultation"
},
"recent_calls": [
{
"id": "00000000-0000-4000-8000-000000000001",
"started_at": "2026-10-19T12:49:15Z",
"duration_s": 248,
"direction": "inbound",
"caller_phone": "+15125550142",
"caller_name": "Maria Lopez",
"contact_id": "00000000-0000-4000-8000-000000000002",
"source": {
"id": "00000000-0000-4000-8000-000000000003",
"type": "ringba",
"name": "Ringba"
},
"campaign": "Spring promo",
"status": "analyzed",
"category": "booked",
"outcome": "open",
"lead_score": 86,
"lead_band": "hot",
"summary": "Maria asked about pricing for a kitchen remodel and booked a consultation for Thursday.",
"labels": [],
"followup_due": "2026-10-20T00:00:00Z",
"ordered": null,
"app_url": "https://listenfox.com/w/acme/calls/00000000-0000-4000-8000-000000000001",
"created_at": "2026-10-19T12:50:15Z",
"updated_at": "2026-10-19T12:53:15Z"
}
],
"call": {
"id": "00000000-0000-4000-8000-000000000001",
"started_at": "2026-10-19T12:49:15Z",
"duration_s": 248,
"direction": "inbound",
"caller_phone": "+15125550142",
"caller_name": "Maria Lopez",
"contact_id": "00000000-0000-4000-8000-000000000002",
"source": {
"id": "00000000-0000-4000-8000-000000000003",
"type": "ringba",
"name": "Ringba"
},
"campaign": "Spring promo",
"status": "analyzed",
"category": "booked",
"outcome": "open",
"lead_score": 86,
"lead_band": "hot",
"summary": "Maria asked about pricing for a kitchen remodel and booked a consultation for Thursday.",
"labels": [],
"followup_due": "2026-10-20T00:00:00Z",
"ordered": null,
"app_url": "https://listenfox.com/w/acme/calls/00000000-0000-4000-8000-000000000001",
"created_at": "2026-10-19T12:50:15Z",
"updated_at": "2026-10-19T12:53:15Z"
},
"ai_generated": true
}
}followup.created example
{
"id": "evt_sample",
"type": "followup.created",
"created_at": "2026-10-19T13:01:15Z",
"workspace_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"data": {
"id": "00000000-0000-4000-8000-000000000004",
"title": "Confirm Thursday's consultation",
"due_at": "2026-10-20T00:00:00Z",
"status": "open",
"call_id": "00000000-0000-4000-8000-000000000001",
"contact_id": "00000000-0000-4000-8000-000000000002",
"assignee": null,
"app_url": "https://listenfox.com/w/acme/calls/00000000-0000-4000-8000-000000000001",
"created_at": "2026-10-19T12:53:15Z",
"ai_generated": true
}
}followup.due example
{
"id": "evt_sample",
"type": "followup.due",
"created_at": "2026-10-19T13:01:15Z",
"workspace_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"data": {
"id": "00000000-0000-4000-8000-000000000004",
"title": "Confirm Thursday's consultation",
"due_at": "2026-10-20T00:00:00Z",
"status": "open",
"call_id": "00000000-0000-4000-8000-000000000001",
"contact_id": "00000000-0000-4000-8000-000000000002",
"assignee": null,
"app_url": "https://listenfox.com/w/acme/calls/00000000-0000-4000-8000-000000000001",
"created_at": "2026-10-19T12:53:15Z"
}
}trigger.fired example
{
"id": "evt_sample",
"type": "trigger.fired",
"created_at": "2026-10-19T13:01:15Z",
"workspace_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"data": {
"trigger": {
"id": "00000000-0000-4000-8000-000000000005",
"name": "Hot lead"
},
"call": {
"id": "00000000-0000-4000-8000-000000000001",
"started_at": "2026-10-19T12:49:15Z",
"duration_s": 248,
"direction": "inbound",
"caller_phone": "+15125550142",
"caller_name": "Maria Lopez",
"contact_id": "00000000-0000-4000-8000-000000000002",
"source": {
"id": "00000000-0000-4000-8000-000000000003",
"type": "ringba",
"name": "Ringba"
},
"campaign": "Spring promo",
"status": "analyzed",
"category": "booked",
"outcome": "open",
"lead_score": 86,
"lead_band": "hot",
"summary": "Maria asked about pricing for a kitchen remodel and booked a consultation for Thursday.",
"labels": [],
"followup_due": "2026-10-20T00:00:00Z",
"ordered": null,
"app_url": "https://listenfox.com/w/acme/calls/00000000-0000-4000-8000-000000000001",
"created_at": "2026-10-19T12:50:15Z",
"updated_at": "2026-10-19T12:53:15Z"
},
"matched": [
{
"field": "lead_band",
"op": "eq",
"value": "hot",
"actual": "hot",
"evidence": null
}
],
"ai_generated": true
}
}order.matched example
{
"id": "evt_sample",
"type": "order.matched",
"created_at": "2026-10-19T13:01:15Z",
"workspace_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"data": {
"order": {
"id": "00000000-0000-4000-8000-000000000006",
"number": "1042",
"total": 129,
"currency": "USD",
"created_at": "2026-10-19T13:01:15Z",
"status": "paid",
"email": "m***@example.com",
"matched_on": "phone",
"after_call": true
},
"call": {
"id": "00000000-0000-4000-8000-000000000001",
"started_at": "2026-10-19T12:49:15Z",
"duration_s": 248,
"direction": "inbound",
"caller_phone": "+15125550142",
"caller_name": "Maria Lopez",
"contact_id": "00000000-0000-4000-8000-000000000002",
"source": {
"id": "00000000-0000-4000-8000-000000000003",
"type": "ringba",
"name": "Ringba"
},
"campaign": "Spring promo",
"status": "analyzed",
"category": "booked",
"outcome": "open",
"lead_score": 86,
"lead_band": "hot",
"summary": "Maria asked about pricing for a kitchen remodel and booked a consultation for Thursday.",
"labels": [],
"followup_due": "2026-10-20T00:00:00Z",
"ordered": null,
"app_url": "https://listenfox.com/w/acme/calls/00000000-0000-4000-8000-000000000001",
"created_at": "2026-10-19T12:50:15Z",
"updated_at": "2026-10-19T12:53:15Z"
}
}
}brief.ready example
{
"id": "evt_sample",
"type": "brief.ready",
"created_at": "2026-10-19T13:01:15Z",
"workspace_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"data": {
"date": "2026-10-18",
"text": "Acme Plumbing: yesterday's calls\n14 calls, 2 missed.",
"app_url": "https://listenfox.com/w/acme",
"ai_generated": false
}
}Headers
| Header | What it holds |
|---|---|
X-ListenFox-Event | The event type, such as call.analyzed. |
X-ListenFox-Delivery | The event id. It stays the same when we retry, so use it to skip events you have already handled. |
X-ListenFox-Timestamp | When we sent this try, in Unix seconds. |
X-ListenFox-Signature-V2 | sha256= followed by the HMAC-SHA256 of the timestamp, a dot and the raw body, signed with your endpoint’s secret. Check this one. |
X-ListenFox-Signature | The older signature, of the body alone. Kept for receivers built before V2. |
User-Agent | ListenFox-Webhooks/1 (formerly CallIntel) |
We also send X-Callintel-Event, X-Callintel-Signature and X-Callintel-Delivery, with the same values, for receivers built before our rename. They stay until at least April 2027. New receivers should use the X-ListenFox-* names.
Check the signature
Anyone can POST to your address, so check every delivery before you trust it. Sign the timestamp, a dot and the raw body with your secret, compare the result with X-ListenFox-Signature-V2, and reject anything older than 5 minutes so a copied delivery can’t be replayed later. Use the body exactly as it arrived: parsing the JSON and turning it back into text changes the bytes, and the check fails.
Python
import hashlib
import hmac
import time
def verify_listenfox(secret: str, headers, body: bytes, tolerance: int = 300) -> bool:
"""True when a delivery really came from ListenFox and is less than 5 minutes old.
headers: the request headers (a case-insensitive mapping, as Flask and FastAPI give you).
body: the raw request body, before any JSON parsing.
"""
stamp = headers.get("X-ListenFox-Timestamp", "")
given = headers.get("X-ListenFox-Signature-V2", "")
if not stamp.isdigit() or abs(time.time() - int(stamp)) > tolerance:
return False
signed = stamp.encode() + b"." + body
expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, given)
import os
from flask import Flask, abort, request
app = Flask(__name__)
@app.post("/hooks/listenfox")
def listenfox_hook():
body = request.get_data() # the raw bytes, exactly as sent
if not verify_listenfox(os.environ["LISTENFOX_WEBHOOK_SECRET"], request.headers, body):
abort(401)
event = request.get_json()
# Answer within 10 seconds. Do slow work after you reply, for example in a queue.
print(event["type"], event["id"])
return "", 200
Node.js
import crypto from "node:crypto";
// True when a delivery really came from ListenFox and is less than 5 minutes old.
// headers: the request headers (Node gives you the names in lower case).
// body: the raw request body as a Buffer or string, before any JSON parsing.
export function verifyListenFox(secret, headers, body, toleranceSeconds = 300) {
const stamp = headers["x-listenfox-timestamp"] ?? "";
const given = headers["x-listenfox-signature-v2"] ?? "";
if (!/^\d+$/.test(stamp) || Math.abs(Date.now() / 1000 - Number(stamp)) > toleranceSeconds) return false;
const expected =
"sha256=" + crypto.createHmac("sha256", secret).update(stamp + ".").update(body).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(given);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
import express from "express";
const app = express();
// express.raw keeps the body as bytes, so the signature can be checked.
app.post("/hooks/listenfox", express.raw({ type: "application/json" }), (req, res) => {
if (!verifyListenFox(process.env.LISTENFOX_WEBHOOK_SECRET, req.headers, req.body)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body);
// Answer within 10 seconds. Do slow work after you reply, for example in a queue.
res.sendStatus(200);
console.log(event.type, event.id);
});
app.listen(3000);
We run both functions above against a real signed delivery whenever this page changes.
Answering a delivery
- Answer with any 2xx status within 10 seconds. The body of your answer is ignored.
- Do slow work after you answer, for example by putting the event on a queue.
- We don’t follow redirects. A 3xx counts as a failure, so give us the final address.
- The same event can arrive more than once, for example when your answer was lost on the way back. Keep the ids you’ve handled and skip repeats. Events can also arrive out of order; use
created_atwhen order matters.
Retries and turning off
When a delivery fails (no answer in 10 seconds, a network error or a status that isn’t 2xx), we try again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours: 8 tries in all, over about two days.
If an endpoint fails 8 times in a row, we turn it off and email the workspace’s owners and admins. Fix your server, then turn the endpoint back on in Settings → Webhooks. Every delivery, with its status and tries, is listed there for 30 days, with a Retry now button.
Testing and catching up
- Send a test event from the endpoint in Settings → Webhooks. It’s signed like a real one.
GET /events/sample?type=call.analyzedreturns one realistic event of that type: your latest real one if there is one, or an example. Handy for mapping fields while you build.GET /eventslists the events of the last 30 days, newest first. After downtime, fetch the ones you missed withsince_id, or poll it instead of receiving webhooks at all.
Both routes are in the API reference. Alerts from triggers that post to a webhook use the same headers and signatures.