Developer docs: Webhooks

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

  1. You give us a public https address on your server (an endpoint) and choose the events you want.
  2. We give you a secret for that endpoint. Store it; it’s shown once.
  3. 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:

Terminal
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.

EventWhen it’s sent
call.createdA call arrived.
call.analyzedA call's analysis finished (the call without its transcript).
call.failedA call could not be analyzed.
lead.hotA contact became a hot lead for the first time.
followup.createdA follow-up was created.
followup.dueA follow-up is due today.
trigger.firedOne of your triggers matched a call.
order.matchedA store order was matched to a call.
brief.readyThe daily brief is ready.
call.created example
POST to your endpoint: call.created
{
  "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
POST to your endpoint: call.analyzed
{
  "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
POST to your endpoint: call.failed
{
  "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
POST to your endpoint: lead.hot
{
  "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
POST to your endpoint: followup.created
{
  "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
POST to your endpoint: followup.due
{
  "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
POST to your endpoint: trigger.fired
{
  "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
POST to your endpoint: order.matched
{
  "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
POST to your endpoint: brief.ready
{
  "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

HeaderWhat it holds
X-ListenFox-EventThe event type, such as call.analyzed.
X-ListenFox-DeliveryThe event id. It stays the same when we retry, so use it to skip events you have already handled.
X-ListenFox-TimestampWhen we sent this try, in Unix seconds.
X-ListenFox-Signature-V2sha256= 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-SignatureThe older signature, of the body alone. Kept for receivers built before V2.
User-AgentListenFox-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

verify.py
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)
In a Flask app
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

verify.mjs
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);
}
In an Express app
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_at when 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.analyzed returns 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 /events lists the events of the last 30 days, newest first. After downtime, fetch the ones you missed with since_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.