Webhooks — tell your systems when something happens
Register an endpoint, the available events, verifying the X-Ragenta-Signature header and reading the delivery log.
Settings → Webhooks. Needs a plan with Webhooks and triggers (Starter and up) and
webhook.manage (Owner/Admin).
We POST a signed JSON body to your server when something happens here — a run finishes, a document finishes indexing.
Register an endpoint
| Field | Notes |
|---|---|
| Name | Internal name. |
| URL | https required. |
| Events to send | Pick from the list below. |
| Enabled | Off pauses it without deleting. |
After saving, SecretOnce shows the whsec_… secret once. New secret on the endpoint
row rotates it (the old one stops working immediately).
Events
| Event | When | data carries |
|---|---|---|
agent.run.succeeded | An agent run finished and produced an answer | runId agentId agentName trigger credits durationMs |
agent.run.failed | An agent run stopped without an answer | runId agentId agentName trigger credits error |
document.ingested | A document finished indexing and is searchable | documentId knowledgeBaseId name chunks |
document.failed | A document could not be indexed | documentId knowledgeBaseId name error |
The body is always { id, event, occurredAt, workspaceId, data }.
Verify the signature
Every request carries X-Ragenta-Event, X-Ragenta-Delivery (a unique id, use it to
de-duplicate) and X-Ragenta-Signature of the form t=<unix>,v1=<hex>.
- Read
tandv1from the header. - Compute
HMAC-SHA256(secret, t + "." + rawBody)and compare its hex withv1(constant-time). - Reject when
tis more than 5 minutes from now — replay protection.
Answer 2xx within a few seconds. Ragenta retries on failure; after 20 consecutive failures the endpoint flips to switched off after failures and you must re-enable it by hand.
Deliveries
Show under an endpoint opens the log: When · Event · Attempt · Result · Took · Your server
said (status code and the start of the response). Status pending · succeeded · failed. Needs
webhook.read.
Embedded chat — put an agent on your website
Publish a chat widget that runs on your site, restrict it to your domains, cap its spend, identify signed-in visitors and watch activity.
Models
The workspace's default chat and embedding models, the catalogue table, tiers by plan, and the order in which a model is chosen.