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.

3 min read Updated

Set up a webhook

  1. Open the Webhooks tab

    In API & Integrations, open Webhooks and click + Webhook.

  2. Choose integration, address and events

    The address must be a public https address. Addresses in internal networks, plain http and redirects are refused.

  3. Copy the secret

    The secret (whsec_…) is shown once. Your server checks every signature with it.

  4. Send a test

    Send test delivers a webhook.test event; 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

TypeWhenNeeds permission
response.completedAn async answer of this integration is ready (the whole response object).chat:write
response.failedAn async answer failed, for example interrupted.chat:write
lead.createdThe agent captured a lead, with all its fields.leads:read
handoff.requestedA conversation was handed to your team.own conversations, or conversations:read_all / livechat:read
handoff.endedThe handoff ended or went back to the agent.as above
handoff.messageA 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.completedAn import, refresh or deletion of knowledge finished.knowledge:read
knowledge.operation.failedIt failed.knowledge:read
credits.lowAt most 10 % of the agent's AI credits are left (once per billing period).credits:read
credits.exhaustedThe 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 "", 200

Delivery 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_at for 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.

Next steps