Webhooks
Webhooks tell your system right away when something happens: a new lead, a handoff to your team, a reply from your team, a finished async answer, a knowledge import or low AI credits.
Set up a webhook
Open the Webhooks tab
In API & Integrations, open Webhooks and click + Webhook.
Choose integration, address and events
The address must be a public
httpsaddress. Addresses in internal networks, plainhttpand redirects are refused.Copy the secret
The secret (
whsec_…) is shown once. Your server checks every signature with it.Send a test
Send test delivers a
webhook.testevent; the delivery log shows the result.
The same works over the API with the permission webhooks:write: POST /v1/webhook-endpoints (returns the secret once), PATCH to change or pause it, POST …/test, POST …/rotate-secret, and GET /v1/events for the delivery log with POST /v1/events/{id}/resend.
The OpenAPI file lists every event under webhooks with the schema of its data and an example. Events are sent only for agents the API serves (api_access), and only from the moment the webhook exists.
Events
| Type | When | Needs permission |
|---|---|---|
response.completed | An async answer of this integration is ready (the whole response object). | chat:write |
response.failed | An async answer failed, for example interrupted. | chat:write |
lead.created | The agent captured a lead, with all its fields. | leads:read |
handoff.requested | A conversation was handed to your team. | own conversations, or conversations:read_all / livechat:read |
handoff.ended | The handoff ended or went back to the agent. | as above |
handoff.message | A person of your team wrote in a conversation. | own conversations, or conversations:read_all (livechat:read is not enough: the event carries the text) |
knowledge.operation.completed | An import, refresh or deletion of knowledge finished. | knowledge:read |
knowledge.operation.failed | It failed. | knowledge:read |
credits.low | At most 10 % of the agent's AI credits are left (once per billing period). | credits:read |
credits.exhausted | The AI credits are used up; answers return 402. | credits:read |
Only events of agents the integration may use are sent. A message looks like this:
HTTP
POST /your/webhook HTTP/1.1
Content-Type: application/json
Ultimo-Signature: t=1794330000,v1=5f3c...e9
Ultimo-Event-Id: evt_3kP9sV2mQ8xL1cT7wB4nZ0aR
Ultimo-Event-Type: lead.created
Ultimo-Delivery-Id: wd_7Hq2Lx9Ma1Bn3Cv5Dz8Ef0Gk
{
"id": "evt_3kP9sV2mQ8xL1cT7wB4nZ0aR",
"object": "event",
"type": "lead.created",
"api_version": "v1",
"created_at": "2026-11-10T17:20:00Z",
"agent_id": "YOUR_AGENT_ID",
"conversation_id": null,
"data": {
"object": "lead", "id": 4711, "agent_id": "YOUR_AGENT_ID", "session_id": "…",
"type": "contact", "read": false, "created_at": "2026-11-10T17:19:58Z",
"fields": {"name": "Anna Schmidt", "email": "anna@example.com", "message": "Please call me back."}
}
}Check the signature
Ultimo-Signature carries the time t (Unix seconds) and one or two v1 values: HMAC-SHA256 of "<t>.<raw body>" with your secret, as hex. Accept the message when one v1 matches and t is less than 5 minutes old. After New secret both the new and the old secret sign for 24 hours, so you can switch without missing a message.
Node.js (Express)
import crypto from "node:crypto";
import express from "express";
const app = express();
// The signature covers the raw body: read it before any JSON parser.
app.post("/ultimo-webhook", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("Ultimo-Signature") || "";
const t = Number(/t=(\d+)/.exec(header)?.[1]);
const given = [...header.matchAll(/v1=([0-9a-f]+)/g)].map((m) => m[1]);
const expected = crypto.createHmac("sha256", process.env.ULTIMO_WEBHOOK_SECRET)
.update(`${t}.`).update(req.body).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - t) < 300;
const valid = given.some((v) => v.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected)));
if (!fresh || !valid) return res.sendStatus(400);
const event = JSON.parse(req.body);
// At least once: skip ids you have already handled (store them for a few days).
if (alreadyHandled(event.id)) return res.sendStatus(200);
queueForProcessing(event); // answer fast, work later
res.sendStatus(200);
});Python (Flask)
import hashlib, hmac, json, os, re, time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["ULTIMO_WEBHOOK_SECRET"].encode()
@app.post("/ultimo-webhook")
def ultimo_webhook():
header = request.headers.get("Ultimo-Signature", "")
t = int(re.search(r"t=(\d+)", header).group(1))
given = re.findall(r"v1=([0-9a-f]+)", header)
raw = request.get_data() # the raw body, not re-serialised JSON
expected = hmac.new(SECRET, f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
if abs(time.time() - t) > 300 or not any(hmac.compare_digest(expected, v) for v in given):
abort(400)
event = json.loads(raw)
if not already_handled(event["id"]): # at least once: deduplicate by event id
queue_for_processing(event)
return "", 200Delivery and retries
- Answer with a 2xx status within 10 seconds. Do slow work after answering.
- Anything else (an error status, a timeout, no connection) is tried 8 times in total: again after about 1 minute, 5 minutes, 30 minutes, 2, 4, 6 and 10 hours: about 23 hours. Every retry carries the same event id.
- Delivery is at least once and not in order. Use
created_atfor order and the event id against duplicates. - A slow or failing receiver only delays its own deliveries, never those of other webhooks.
- When every delivery to an address has failed for 3 days, the webhook is paused and the workspace owner gets an e-mail. Fix the server, click Resume, and send missed events again from the log.
- The delivery log shows every delivery (time, status, number of attempts) for 30 days. Send again repeats any delivery.