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

EventWhen
message.receivedWhen a customer sends a new message
message.sentWhen the AI, an agent, a campaign or the API sends a message
conversation.handoffWhen a conversation is handed off to a human
contact.createdWhen someone messages the bot for the first time and is saved
contact.consent_changedWhen a contact opts in or out of campaigns/notifications (STOP, dashboard, API, block)
campaign.completedWhen a campaign finishes sending
post.publishedWhen a post from the content calendar is sent to a channel or group
miniapp.submissionWhen a Mini App form or order request is submitted
miniapp.order_updatedWhen 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

JSON
{
  "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" }
  }
}
HeaderMeaning
X-Hiboty-EventEvent name
X-Hiboty-DeliveryDelivery ID; stays the same on retries, store it to avoid processing twice
X-Hiboty-TimestampWhen the signature was created (Unix seconds)
X-Hiboty-Signaturesha256= 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-Delivery to drop duplicates.
  • Delivery order isn't guaranteed; check the created_at field.

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"