raia cX · Section
Organization Webhooks
Send signed alerts, security events and scheduled agent health checks from raia to your own apps.
Audience: Organization owners, organization administrators, and the developers who build the apps that receive raia events.
What organization webhooks do
An organization webhook sends a message from raia to your own app when something important happens. Your app might be an alerting tool, a ticketing system, a monitoring dashboard, or a small service you write yourself.
You can use organization webhooks to:
- Get alerts about conversations. For example, raia can tell your app when an agent escalates a conversation or when an alert is raised.
- Watch for security events. raia can report failed logins and temporary lockouts for members of your organization.
- Check that your agents are healthy. On a schedule you choose, raia asks each agent a short question and reports whether it answered, how long it took, and what went wrong if it did not.
Each message is an HTTP POST request with a JSON body, sent to an address (an endpoint URL) that you choose. Your organization can have up to 20 webhooks.
These webhooks belong to the whole organization. They are separate from the Webhooks skill on a single agent, which sends conversation data when a message or thread ends.
Before you begin
| Requirement | Why you need it |
|---|---|
| Org Owner or Org Admin role in raia CX | Only owners and admins can open, create, and change organization webhooks. |
An HTTPS endpoint that accepts POST requests | raia delivers every event to this address. A developer usually builds or configures it. |
| A safe place to store a secret on the receiving server | You use the signing secret or custom header values to confirm that a request really came from raia. |
Open the Webhooks page
- In raia CX, open Organization, then Webhooks.
- The page lists your organization's webhooks. Each row shows whether the webhook is on, its name, its URL, the events it listens for, which agents it covers, and when it was last updated.
- Use the search box to find a webhook, or the edit and delete actions on a row.
- Select Add webhook to create a new one, or select a webhook to open its detail page.
Create a webhook
The create and edit form has three tabs: Events, Agents, and Instructions. Fill in the fields below, then save.
| Field | Required | What to enter |
|---|---|---|
| Endpoint URL | Yes | The full web address of your receiving app. HTTP and HTTPS addresses are accepted; use HTTPS for real use. |
| Name | No | A short label shown in the webhooks table, up to 255 characters. |
| Description | No | A note for your team about what this webhook is for. |
| Authentication | Yes | Signing secret (the default) or Custom headers. See the sections below. |
| Custom headers | Only with Custom headers | At least one header name and value. |
| Events | Yes | At least one event. The Agent health check event also asks how often to run. |
| Agent scope | Yes | All agents, or a list of specific agents. |
The Instructions tab explains how to connect your app. It includes a Node.js (Express) example you can copy, matched to the authentication method you chose.
When you create a webhook with a signing secret, raia shows the full secret only once. Copy it into your receiving server's secret storage before you close the window. After that, raia shows only the last four characters.
Choose events
Events are grouped into Conversations, Security, and Agents. A webhook can listen for any mix of them. In each delivery, the type field tells your app which event it is.
| Group | Event | type value | Sent when |
|---|---|---|---|
| Conversations | Conversation escalation created | conversation.escalation.created | A conversation is escalated. |
| Conversations | Conversation auditor alert created | conversation.auditor_alert.created | An Auditor alert is raised on a conversation. |
| Conversations | Conversation alert created | conversation.alert.created | A conversation alert is raised. |
| Conversations | Conversation alert resolved | conversation.alert.resolved | A conversation alert is resolved, either by a person or by a message-limit change. |
| Security | Failed login | user.login.failed | A member fails a password or two-factor sign-in. |
| Security | Login lockout | user.login.locked_out | A member is temporarily blocked after too many failed attempts. |
| Agents | Agent health check | agent.health_check | On the interval you choose, raia checks each agent in scope and reports the result. |
Good to know:
- Security events go to every organization the member belongs to. If a member belongs to two organizations, a failed login creates an event in each one.
- Agent scope applies to agent events. If a webhook covers only some agents, it receives conversation and health-check events for those agents only.
- Preview before you send. In the event picker, you can preview each event's sample JSON without sending anything.
What each event includes
Every event's data object includes the organization. The rest depends on the event:
| Event | Fields in data |
|---|---|
| Conversation escalation created | agent (id, name), conversation (id, url), escalation (id) |
| Conversation auditor alert created | agent, conversation, auditorAlert (id, type) |
| Conversation alert created | agent, conversation, conversationAlert (id, type) |
| Conversation alert resolved | agent, conversationAlert (id, type). There is no conversation field. |
| Failed login | user (id, email), attempt (method, reason) |
| Login lockout | user (id, email), attempt (method) |
| Agent health check | agent, healthCheck (see below) |
Set up agent health checks
An agent health check is a quick, scheduled test that tells you whether each agent is still answering.
- In the Events tab, select Agent health check.
- Choose how often to run it: every 15, 30, 45, or 60 minutes. The default is 60.
- In the Agents tab, choose All agents or select the agents you want to monitor.
- Save the webhook.
On each run, raia sends every agent in scope the prompt “Health check: reply with OK.” and waits up to two minutes for a reply. It then sends an agent.health_check event with the result. Checks are scheduled in 15-minute slots, so a check can arrive a little after the exact minute you expect.
Each check is a real prompt to the agent, and the event reports the tokens it used. Choose an interval that suits how quickly you need to know about a problem.
Read a health-check result
The healthCheck object tells you what happened:
| Field | What it tells you |
|---|---|
status | ok, error, timeout, quota_exceeded, or subscription_inactive. |
responding | Whether the agent replied. |
latencyMs | How long the reply took, in milliseconds. |
intervalMinutes, timeoutMs | The interval you chose and the time raia waited. |
scheduledAt, startedAt, completedAt | When the check was due, started, and finished. |
nextExpectedAt | When to expect the next check. If nothing arrives by then, investigate. |
prompt, response | The prompt sent and the agent's reply. response.text is cut to 500 characters, and response.truncated says whether it was cut. |
model | The configured and actual model, the provider, and settings such as temperature. |
usage | Total, input, output, and reasoning tokens. |
usedFunctionsCount | How many functions the agent called. |
error | provider_error, rate_limited, context_window_exceeded, configuration_error, internal_error, or null. |
A simple alerting rule is: raise an alert when status is not ok, or when no check arrives by nextExpectedAt.
What your app receives
Every delivery is an HTTP POST to your endpoint URL with these headers:
| Header | When it is sent | Purpose |
|---|---|---|
Content-Type: application/json | Always | The body is JSON. |
Raia-Event-Id | Always | A unique ID for the event. The same event keeps the same ID, so you can skip repeats. |
Raia-Signature | Signing secret only | A signature your app checks to confirm the request came from raia. |
| Your custom headers | Custom headers only | The exact names and values you set on the webhook. |
The body always has the same shape:
{
"id": "evt_<resourceId>",
"type": "conversation.escalation.created",
"created": 1763510400,
"isTest": false,
"data": {
"organization": { "id": "…" },
"agent": { "id": "…", "name": "…" },
"conversation": { "id": "…", "url": "…" },
"escalation": { "id": "…" }
}
}idis the event ID. It matches theRaia-Event-Idheader.typeis one of the event values listed above.createdis a Unix timestamp in seconds.isTestistruefor test events andfalsefor real ones.dataholds the event's details.
Delivery limits
| Limit | Value |
|---|---|
| Largest request body raia sends | 256 KB |
| Response body raia reads from your app | Up to 64 KB |
| Time raia waits for each attempt | 15 seconds |
| Redirects | Not followed |
| What counts as success | Any 2xx response |
Reply quickly with a 2xx status, then do slower work in the background. If your endpoint redirects, raia treats the delivery as failed, so use the final URL.
Check the signature
With the Signing secret method, each delivery has a Raia-Signature header. Checking it proves the request came from raia and was not changed on the way.
The header looks like this:
Raia-Signature: t=1763510400,v1=5f2b…tis the time raia signed the request, in Unix seconds.v1is an HMAC-SHA256 digest, in hex, of the text<t>.<raw request body>, using your signing secret as the key.
To check it:
- Accept
POSTrequests withContent-Type: application/jsonon an HTTPS endpoint. - Read the raw request body before you parse the JSON. The signature covers the exact bytes raia sent.
- Split
Raia-Signatureintotandv1. - Compute HMAC-SHA256 of
t + "." + rawBodywith your secret, and compare it withv1using a constant-time comparison. - If they match, parse the JSON, handle the event, and reply with a
2xxstatus. - Store each
Raia-Event-Idyou have handled, and skip any you have already seen.
Here is a minimal Node.js (Express) example. Keep the secret in an environment variable, never in your code.
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.RAIA_WEBHOOK_SECRET; // whsec_…
app.post("/raia/webhooks", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("Raia-Signature") ?? "";
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
const expected = crypto
.createHmac("sha256", SECRET)
.update(`${parts.t}.`)
.update(req.body) // the raw bytes, before JSON parsing
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1 ?? "");
const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
if (!valid) return res.status(401).end();
const event = JSON.parse(req.body.toString("utf8"));
res.status(200).end(); // reply first, then process
handleEvent(event); // your code: skip repeated event.id values
});You can also reject requests whose t value is much older than the current time, for example more than five minutes. This is a recommended extra check; raia does not require it.
Rotate the signing secret
On the webhook's detail page, select Rotate secret and confirm. raia creates a new secret straight away and shows it once.
There is no overlap period. From the moment you rotate, raia signs deliveries with the new secret only. Update the secret on your receiving server at the same time, or plan a short window where some deliveries may fail the check.
Use custom headers instead
If your app already checks a header such as an API key, choose Custom headers. raia then sends the names and values you set, for example Authorization: Bearer …, on every delivery.
- There is no
Raia-Signatureheader in this mode.Raia-Event-Idis still sent. - Add at least one header.
- You cannot use these reserved names:
Content-Type,Content-Length,Host,Raia-Signature,Raia-Event-Id,Connection,Transfer-Encoding. - Treat header values like passwords. Keep the expected values in environment variables on your server, and compare them before you trust the body.
The Instructions tab lists the header names you set and shows an Express example that checks them.
Send a test event
Test every webhook before you rely on it.
- Open the webhook's detail page.
- Select Send test event.
- Choose one of the webhook's events.
raia sends a real request to your endpoint with that event's sample data and the webhook's real signature or headers. The body has isTest: true, and the event ID looks like evt_test_<webhookId>_<timestamp>. If your endpoint does not accept it, raia shows an error.
In your app, check isTest so that test events do not open real tickets or page anyone.
Retries and failed deliveries
raia sends events in the background, so a slow endpoint never holds up the action that caused the event.
- Up to three attempts. If an attempt fails, raia waits 1 second, then 2 seconds, before trying again.
- What is retried: network errors, HTTP
429, and any5xxresponse. - What is not retried: other
4xxresponses, and responses larger than 64 KB. - After the last attempt the event is dropped. raia does not keep a queue of failed events or replay them later.
- Each webhook is separate. If one endpoint fails, raia still delivers to your other webhooks.
Because a failed event is not replayed, watch your endpoint's own logs and alert on errors. For health checks, nextExpectedAt helps you notice missing deliveries.
Turn off, edit, or delete a webhook
- Turn off or on: use the switch in the table, or Activate / Deactivate on the detail page. A webhook that is off keeps its settings but receives nothing. The detail page shows Active or Inactive.
- Edit: change the URL, events, agents, or authentication, then save.
- Delete: select delete and confirm. raia stops sending events to that URL, and this cannot be undone.
Quick checklist
- [ ] The endpoint uses HTTPS and replies with a
2xxstatus within 15 seconds. - [ ] The signing secret or header values are stored in environment variables, not in code.
- [ ] Your app checks
Raia-Signatureagainst the raw body, or checks your custom headers. - [ ] Your app skips repeated
Raia-Event-Idvalues. - [ ] Your app handles
isTest: truesafely. - [ ] You sent a test event for each event type you use.
- [ ] For health checks, you alert when
statusis notokor a check is late.