orka.Developers
Developers / REST API

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

  1. In the dashboard, go to Settings → Developers → Webhooks, or use POST /webhook-endpoints.
  2. Click Add endpoint, name it, paste your HTTPS URL and pick the events you want.
  3. Orka shows the signing secret of the endpoint (whsec_…). Copy it, it is shown once.
  4. 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

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.