Integration
Webhooks
Receive events on your own server — subscription, signature verification, retries and the event catalogue.
A webhook is Blesyum POSTing to your server when something happens. Instead of polling, you wait for the event.
Subscribing
Panel → Developer → Webhooks → New endpoint
You give two things: an address and the events you want. In return you get a signing secret (prefixed whsec_) — shown once.
Event names are validated against the catalogue. A misspelling (conversation.creted) now returns 400. It used to return 201, create the subscription, and deliver nothing — a failure that surfaced days later as "my webhook doesn't work".
The catalogue narrows to your licence: an event from a module you are not subscribed to never appears. An event you can select but will never receive is an event silently missed.
The delivery request
POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Blesyum-Event: conversation.created
X-Blesyum-Delivery: 0193c4e2-…
X-Blesyum-Signature: 5f3a9c…| Header | Carries |
|---|---|
X-Blesyum-Event | Event type |
X-Blesyum-Delivery | Delivery id — for duplicate detection |
X-Blesyum-Signature | Hex HMAC-SHA256(secret, raw body) |
VERIFY the signature
This step is not optional: anyone who knows your address can post to it.
import { createHmac, timingSafeEqual } from "node:crypto";
export function signatureValid(rawBody: string, signature: string, secret: string): boolean {
const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected, "utf8");
const b = Buffer.from(signature, "utf8");
// timingSafeEqual THROWS on length mismatch; compare lengths first.
if (a.length !== b.length) return false;
// 🔴 Do NOT use plain `===`: comparison time varies with the number of
// matching characters, letting an attacker guess the signature byte by byte.
return timingSafeEqual(a, b);
}import hmac, hashlib
def signature_valid(raw_body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)The signature is computed over the raw body. If you parse the JSON and re-serialise it, whitespace and key order change and the signature will not match. Take the body as bytes, verify, then parse.
Your response matters
- Return 2xx — the delivery counts as successful.
- Return fast. Queue the work and reply 200; a long-running handler times out and the event is retried.
- Anything other than 2xx is a failure and is retried.
An endpoint that keeps failing is temporarily disabled; the panel shows you why (status code and error text).
Duplicate deliveries
Networks are uncertain: an event you answered with 200 may arrive again. Store the X-Blesyum-Delivery id and ignore what you have seen. This is the natural consequence of at-least-once delivery and is solved on your side.
Test environment
An API key in the test environment does not trigger live side effects: webhooks are not delivered. You can exercise your integration against real data, quietly.
Events
The catalogue is in the panel and at GET /api/v1/webhooks/catalog. Some CRM events:
| Event | When |
|---|---|
conversation.created | A conversation opened (widget · email · panel · API — all of them) |
conversation.replied | A reply arrived |
conversation.closed | A conversation was closed |
conversation.snoozed | A conversation was snoozed |
contact.created · contact.updated · contact.deleted | Contact record |
The event is emitted inside the shared gate that writes the record, in the same database transaction. So a conversation fires the event whichever way it was opened (live chat, inbound email, panel, API) — no branch of the gate can have been forgotten.