Webhook events
Xara sends each event as a JSON POST to the assistant's webhook URL.
| Header | Value |
|---|---|
Content-Type | application/json |
X-Xara-Event | The event name, such as assistant.message. |
X-Xara-Delivery-Id | The message id. Retries reuse it. |
X-Xara-Signature | Base64 HMAC-SHA256 of the raw body, keyed with the webhook secret. |
Answer with any 2xx status within 15 seconds. Reply to the customer with a separate API call, not in the webhook response.
Verify the signature
Compute the HMAC over the raw request body before parsing it, and compare in constant time.
import crypto from "node:crypto";
export function isFromXara(rawBody: string, signature: string | undefined): boolean {
const expected = crypto
.createHmac("sha256", process.env.XARA_ASSISTANT_SECRET!)
.update(rawBody)
.digest("base64");
const given = Buffer.from(signature ?? "");
const want = Buffer.from(expected);
return given.length === want.length && crypto.timingSafeEqual(given, want);
}
Reject any request whose signature doesn't match.
assistant.message
A customer sent a message.
{
"event": "assistant.message",
"id": "48213",
"assistant": { "ref": "bolt-orders-3f9a1c2e", "name": "Bolt Orders", "branding": "Friendly, short replies." },
"business": { "id": 12, "name": "Bolt Foods" },
"customer": { "id": 901, "name": "Ada Obi", "phone": "2348012345678" },
"message": {
"id": "48213",
"type": "text",
"text": "Do you deliver to Yaba?",
"reply_to": null,
"forwarded": false,
"sent_at": "2026-11-03T10:14:22.000Z"
}
}
| Field | Description |
|---|---|
assistant.ref | Pass it as ref when you reply. |
assistant.branding | Your notes for the bot. Left out when empty. |
customer.id | Pass it as customer_id when you reply. |
message.id | Pass it as reply_to to quote this message. |
message.type | text, image, or audio. |
message.reply_to | The id of the message the customer quoted, or null. |
message.status | Present when the customer replied to one of the assistant's updates: its id, type, and text. |
message.reply | Present when the customer tapped one of your buttons or list rows: its type (button or list), and the id and title you gave it. |
A tapped option looks like this:
{
"message": {
"id": "48215",
"type": "text",
"text": "Pick up",
"reply": { "type": "button", "id": "pickup", "title": "Pick up" }
}
}
A photo or voice note adds mime_type and file_url, and a voice note adds duration_ms. file_url is a signed link you can GET for one day; download the file if you need it longer.
assistant.payment
A customer paid in the chat. The payload is the same as assistant.message with a payment object:
{
"event": "assistant.payment",
"payment": {
"amount": 2000,
"currency": "NGN",
"status": "completed",
"note": "Jollof rice x2",
"payment_id": 77120,
"reference": "XRA-77120",
"request_id": "k2J9xQ0aP4mWc7rT1zYb",
"xara_charge": 40,
"amount_received": 1960
}
}
request_id matches the one ChatAssistant/requestPayment returned, so you know which request was paid. A customer can also send money without a request; then there is no request_id. The money is already in your business wallet when the event arrives.
amount is what the customer paid. Xara's charge, xara_charge, comes out of it, and amount_received is what reached your business wallet. Both are in naira; xara_charge is 0 when there is no charge.
assistant.mention
Someone mentioned the assistant in a group chat, as @ and its name. The payload is the same as assistant.message with a group object; customer is whoever mentioned it.
{
"event": "assistant.mention",
"group": { "id": 3120, "name": "Friday lunch" }
}
Only text messages can mention an assistant, and the assistant sees only those messages, not the rest of the group. Mentions of people in message.text show their names. Answer with ChatAssistant/reply and group_id set to group.id; see Reply to a customer.
assistant.ping
Sent when you select Test webhook in the dashboard or call ChatAssistant/test. It is signed like every other event. Answer 2xx; there is nothing to do.
{
"event": "assistant.ping",
"id": "ping-5c1e0a9f7b2d4e61",
"assistant": { "ref": "bolt-orders-3f9a1c2e", "name": "Bolt Orders" },
"sent_at": "2026-11-03T10:14:22.000Z"
}
Retries
If your webhook doesn't answer 2xx, Xara tries again after 1 minute, 5 minutes, and 30 minutes, then gives up. Every attempt has the same X-Xara-Delivery-Id, so ignore ids you've already handled.