Webhooks
Available on the Max plan.
Webhooks are HTTP callbacks sent to a URL of yours when something happens in a project: a visitor leaves their email, a message arrives, a conversation is resolved. Use them to feed your CRM, post to Slack, or trigger your own automations, without polling the API.
Setup
- In the dashboard, go to Settings → Developers → Webhooks, or use
POST /webhook-endpoints. - Click Add endpoint, name it, paste your HTTPS URL and pick the events you want.
- Orka shows the signing secret of the endpoint (
whsec_…). Copy it, it is shown once. - Verify the signature of every request with that secret, see below.
Up to 10 endpoints per project. Each has its own secret and its own list of events.
The events
| Event | Fired when |
|---|---|
conversation.created |
The first message of a conversation is sent, by the visitor or by your team. |
conversation.identified |
The visitor of an ongoing conversation gets an email (typed in the chat, sent by the SDK or set by your team) and is linked to a contact. This is the one to plug into your CRM. |
conversation.assigned |
A conversation is assigned to a teammate, or unassigned. |
conversation.resolved |
A conversation is marked as resolved. |
conversation.reopened |
A resolved conversation is reopened, by a teammate or by a new message of the visitor. |
message.created |
A message is added to a conversation: by the visitor, a teammate, the AI agent or a bot. Private notes included, check is_private. |
contact.created |
A contact is created, from the chat, the dashboard or the API. |
contact.updated |
The email, the name, the avatar, the attributes or the blocked state of a contact change. |
webhook.ping |
You clicked Test, or called POST /webhook-endpoints/{id}/ping. |
The payload of each event is described in the API reference, under Webhooks.
The request
POST /your/path HTTP/1.1
Content-Type: application/json
User-Agent: Orka-Webhooks/1.0
X-Orka-Event-Id: evt_7d1f0a52c4e94b0f8a6de1b2c3d4e5f6
X-Orka-Event-Type: conversation.identified
X-Orka-Timestamp: 1790000000
X-Orka-Signature: t=1790000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
{
"id": "evt_7d1f0a52c4e94b0f8a6de1b2c3d4e5f6",
"type": "conversation.identified",
"created_at": "2026-09-21T14:03:12.000Z",
"project_id": "65f1c0a9e4b0a1b2c3d4e5f6",
"data": {
"id": "66b1…",
"status": "open",
"contact": { "id": "66a9…", "email": "[email protected]", "name": "Ada Lovelace", "email_verified": false },
"…": "…"
}
}
| Header | Description |
|---|---|
X-Orka-Event-Id |
Unique ID of the event. The same ID is sent again when the delivery is retried: use it to deduplicate. |
X-Orka-Event-Type |
Same as type in the body. |
X-Orka-Timestamp |
Unix time in seconds, when the request was signed. |
X-Orka-Signature |
t=<timestamp>,v1=<hex signature>. |
data is the resource as the REST API returns it at the time of the event. conversation.assigned also carries a previous object with the old value: { "assignee_id": null }.
A visitor identified by the SDK before they write has no conversation yet: their contact comes with conversation.created, in data.contact. Listen to both events to catch every email.
Verify the signature
Anyone can find your URL and post to it. The signature proves the request comes from Orka, and that it is recent.
The signature is HMAC-SHA256(secret, timestamp + "." + raw_body), in hex. Compute it over the raw body, byte for byte as received: parsing the JSON and serializing it again changes the bytes and breaks the signature.
// Node.js, Express
import crypto from "crypto";
import express from "express";
const app = express();
app.post("/webhooks/orka", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("X-Orka-Signature") || "";
const { t, v1 } = Object.fromEntries(header.split(",").map((part) => part.split("=")));
const expected = crypto.createHmac("sha256", process.env.ORKA_WEBHOOK_SECRET).update(`${t}.${req.body}`).digest("hex");
const valid = v1 && v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300; // 5 minutes
if (!valid || !fresh) {
return res.sendStatus(400);
}
const event = JSON.parse(req.body);
if (event.type === "webhook.ping") {
return res.sendStatus(200);
}
queue.add(event); // answer first, work later
res.sendStatus(200);
});
# Python, Flask
import hmac, hashlib, os, time
from flask import Flask, request, abort
app = Flask(__name__)
@app.post("/webhooks/orka")
def orka_webhook():
parts = dict(p.split("=", 1) for p in request.headers.get("X-Orka-Signature", "").split(",") if "=" in p)
signed = f"{parts.get('t')}.".encode() + request.get_data()
expected = hmac.new(os.environ["ORKA_WEBHOOK_SECRET"].encode(), signed, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, parts.get("v1", "")):
abort(400)
if abs(time.time() - int(parts["t"])) > 300:
abort(400)
event = request.get_json()
return "", 200
Reject timestamps older than 5 minutes: it stops someone who captured a real request from replaying it later.
Delivery and retries
- Answer with any
2xxstatus within 10 seconds. Anything else, redirects included, is a failure. Do the slow work after answering. - A failed delivery is retried up to 8 times over about 24 hours: after 1 minute, 5 minutes, 30 minutes, 2 hours, then every 5 hours.
- Retries reuse the same
X-Orka-Event-Id. A delivery can also arrive twice after a timeout on a request you did process: deduplicate on the event ID. - Order is not guaranteed. Use
created_at, or fetch the resource from the API when order matters. - When nothing was accepted for 3 days and an event has used all its retries, the endpoint is disabled and the owner of the project gets an email. One success resets the 3 days. Re-enable it from the dashboard, or with
PATCH /webhook-endpoints/{id}. - Every delivery is logged for 30 days, with what your server answered:
GET /webhook-endpoints/{id}/deliveries. The dashboard shows the last 100 and lets you send a failed one again. - Pausing an endpoint (
is_active: false) cancels its pending retries. Events that happen while it is paused are not sent later. - URLs must be public HTTPS URLs. Private and local addresses are refused.
Test with webhook.ping
The Test button of an endpoint, or POST /webhook-endpoints/{id}/ping, sends a webhook.ping event: same headers and same signature as a real event, with a dummy payload. It is sent once, without retries: the response is returned right away.
{
"id": "evt_2b86f80…",
"type": "webhook.ping",
"created_at": "2026-09-21T14:03:12.000Z",
"project_id": "65f1c0a9e4b0a1b2c3d4e5f6",
"data": { "message": "This is a test event from Orka. If you can read this, your endpoint is reachable." }
}
It gives you a real signed request to check your verification code without starting a fake conversation. During development, a tunnel (ngrok, Cloudflare Tunnel) or a request inspector such as webhook.site does the job.