Skip to content

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

RequirementWhy you need it
Org Owner or Org Admin role in raia CXOnly owners and admins can open, create, and change organization webhooks.
An HTTPS endpoint that accepts POST requestsraia delivers every event to this address. A developer usually builds or configures it.
A safe place to store a secret on the receiving serverYou use the signing secret or custom header values to confirm that a request really came from raia.

Open the Webhooks page

  1. In raia CX, open Organization, then Webhooks.
  2. 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.
  3. Use the search box to find a webhook, or the edit and delete actions on a row.
  4. 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.

FieldRequiredWhat to enter
Endpoint URLYesThe full web address of your receiving app. HTTP and HTTPS addresses are accepted; use HTTPS for real use.
NameNoA short label shown in the webhooks table, up to 255 characters.
DescriptionNoA note for your team about what this webhook is for.
AuthenticationYesSigning secret (the default) or Custom headers. See the sections below.
Custom headersOnly with Custom headersAt least one header name and value.
EventsYesAt least one event. The Agent health check event also asks how often to run.
Agent scopeYesAll 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.

GroupEventtype valueSent when
ConversationsConversation escalation createdconversation.escalation.createdA conversation is escalated.
ConversationsConversation auditor alert createdconversation.auditor_alert.createdAn Auditor alert is raised on a conversation.
ConversationsConversation alert createdconversation.alert.createdA conversation alert is raised.
ConversationsConversation alert resolvedconversation.alert.resolvedA conversation alert is resolved, either by a person or by a message-limit change.
SecurityFailed loginuser.login.failedA member fails a password or two-factor sign-in.
SecurityLogin lockoutuser.login.locked_outA member is temporarily blocked after too many failed attempts.
AgentsAgent health checkagent.health_checkOn 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:

EventFields in data
Conversation escalation createdagent (id, name), conversation (id, url), escalation (id)
Conversation auditor alert createdagent, conversation, auditorAlert (id, type)
Conversation alert createdagent, conversation, conversationAlert (id, type)
Conversation alert resolvedagent, conversationAlert (id, type). There is no conversation field.
Failed loginuser (id, email), attempt (method, reason)
Login lockoutuser (id, email), attempt (method)
Agent health checkagent, 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.

  1. In the Events tab, select Agent health check.
  2. Choose how often to run it: every 15, 30, 45, or 60 minutes. The default is 60.
  3. In the Agents tab, choose All agents or select the agents you want to monitor.
  4. 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:

FieldWhat it tells you
statusok, error, timeout, quota_exceeded, or subscription_inactive.
respondingWhether the agent replied.
latencyMsHow long the reply took, in milliseconds.
intervalMinutes, timeoutMsThe interval you chose and the time raia waited.
scheduledAt, startedAt, completedAtWhen the check was due, started, and finished.
nextExpectedAtWhen to expect the next check. If nothing arrives by then, investigate.
prompt, responseThe prompt sent and the agent's reply. response.text is cut to 500 characters, and response.truncated says whether it was cut.
modelThe configured and actual model, the provider, and settings such as temperature.
usageTotal, input, output, and reasoning tokens.
usedFunctionsCountHow many functions the agent called.
errorprovider_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:

HeaderWhen it is sentPurpose
Content-Type: application/jsonAlwaysThe body is JSON.
Raia-Event-IdAlwaysA unique ID for the event. The same event keeps the same ID, so you can skip repeats.
Raia-SignatureSigning secret onlyA signature your app checks to confirm the request came from raia.
Your custom headersCustom headers onlyThe exact names and values you set on the webhook.

The body always has the same shape:

json
{
  "id": "evt_<resourceId>",
  "type": "conversation.escalation.created",
  "created": 1763510400,
  "isTest": false,
  "data": {
    "organization": { "id": "…" },
    "agent": { "id": "…", "name": "…" },
    "conversation": { "id": "…", "url": "…" },
    "escalation": { "id": "…" }
  }
}
  • id is the event ID. It matches the Raia-Event-Id header.
  • type is one of the event values listed above.
  • created is a Unix timestamp in seconds.
  • isTest is true for test events and false for real ones.
  • data holds the event's details.

Delivery limits

LimitValue
Largest request body raia sends256 KB
Response body raia reads from your appUp to 64 KB
Time raia waits for each attempt15 seconds
RedirectsNot followed
What counts as successAny 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:

text
Raia-Signature: t=1763510400,v1=5f2b…
  • t is the time raia signed the request, in Unix seconds.
  • v1 is an HMAC-SHA256 digest, in hex, of the text <t>.<raw request body>, using your signing secret as the key.

To check it:

  1. Accept POST requests with Content-Type: application/json on an HTTPS endpoint.
  2. Read the raw request body before you parse the JSON. The signature covers the exact bytes raia sent.
  3. Split Raia-Signature into t and v1.
  4. Compute HMAC-SHA256 of t + "." + rawBody with your secret, and compare it with v1 using a constant-time comparison.
  5. If they match, parse the JSON, handle the event, and reply with a 2xx status.
  6. Store each Raia-Event-Id you 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.

js
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-Signature header in this mode. Raia-Event-Id is 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.

  1. Open the webhook's detail page.
  2. Select Send test event.
  3. 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 any 5xx response.
  • What is not retried: other 4xx responses, 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 2xx status within 15 seconds.
  • [ ] The signing secret or header values are stored in environment variables, not in code.
  • [ ] Your app checks Raia-Signature against the raw body, or checks your custom headers.
  • [ ] Your app skips repeated Raia-Event-Id values.
  • [ ] Your app handles isTest: true safely.
  • [ ] You sent a test event for each event type you use.
  • [ ] For health checks, you alert when status is not ok or a check is late.