Developers
Outgoing webhooks
Receive message, contact, campaign and order events in your own system.
Setup
Register your HTTPS endpoint under Settings → Webhooks or with createWebhook; the events you select are POSTed as JSON. Each organization can have up to 10 webhooks. Each webhook has its own signing secret (whsec_…), shown only at creation. localhost and private network addresses can't be registered.
Events
| Event | When |
|---|---|
message.received | When a customer sends a new message |
message.sent | When the AI, an agent, a campaign or the API sends a message |
conversation.handoff | When a conversation is handed off to a human |
contact.created | When someone messages the bot for the first time and is saved |
contact.consent_changed | When a contact opts in or out of campaigns/notifications (STOP, dashboard, API, block) |
campaign.completed | When a campaign finishes sending |
post.published | When a post from the content calendar is sent to a channel or group |
miniapp.submission | When a Mini App form or order request is submitted |
miniapp.order_updated | When a Mini App order's status is changed in the dashboard or through the API |
You don't subscribe to the ping event: it's the test event sent from the dashboard or with testWebhook.
Example payload and headers
{
"id": "5b1c0d8e-6c1f-4f0a-9a57-2b7d8e1f4c33",
"event": "message.received",
"created_at": "2026-11-06T09:00:00.000Z",
"organization_id": "…",
"data": {
"message": { "id": "…", "body": "Hi, what's the price?", "created_at": "…" },
"conversation": { "id": "…", "status": "open" },
"contact": { "id": "…", "channel": "telegram", "external_id": "123456789", "name": "Jane" },
"bot": { "id": "…", "name": "Sales Assistant", "channel": "telegram" }
}
}| Header | Meaning |
|---|---|
X-Hiboty-Event | Event name |
X-Hiboty-Delivery | Delivery ID; stays the same on retries, store it to avoid processing twice |
X-Hiboty-Timestamp | When the signature was created (Unix seconds) |
X-Hiboty-Signature | sha256= followed by the hex value of HMAC-SHA256(secret, timestamp + "." + body) |
Signature verification
Verify every request before processing it. Reject requests older than 5 minutes (replay protection).
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyHibotySignature(headers, rawBody, secret) {
const timestamp = headers["x-hiboty-timestamp"];
const signature = headers["x-hiboty-signature"] ?? ""; // "sha256=…"
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}Sign the raw (unparsed) body; if the JSON is re-serialized the signature won't match. Your endpoint must return a 2xx within 10 seconds; queue heavy work.
Receiver example
A minimal receiver with Express and Flask: reads the raw body, verifies the signature and returns a 2xx. These samples need the express or flask package.
import express from "express";
import { verifyHibotySignature } from "./verify.mjs";
const app = express();
// Read the body raw (Buffer): re-serialized JSON won't match the signature.
app.post("/hiboty-webhook", express.raw({ type: "application/json" }), (req, res) => {
if (!verifyHibotySignature(req.headers, req.body.toString("utf8"), process.env.HIBOTY_WEBHOOK_SECRET)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body);
console.log(req.headers["x-hiboty-delivery"], event.event);
res.sendStatus(200);
});
app.listen(3000);Retries and disabling
Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h and 12 h. After 50 consecutive failed deliveries the webhook is turned off (active: false); turn it back on in the dashboard or with POST /api/v1/webhooks/{id}/enable.
- A successful delivery resets the consecutive failure counter; turning the webhook back on resets it too.
- The same event can be sent again: use
X-Hiboty-Deliveryto drop duplicates. - Delivery order isn't guaranteed; check the
created_atfield.
Monitoring deliveries
Delivery history shows the status, attempts and error; the event payload isn't returned because it can carry personal data.
curl "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/deliveries?limit=20" -H "Authorization: Bearer $HIBOTY_API_KEY"
curl -X POST "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/test" -H "Authorization: Bearer $HIBOTY_API_KEY"
curl -X POST "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/enable" -H "Authorization: Bearer $HIBOTY_API_KEY"