Webhooks

What a webhook delivers

Ray9 emits immutable events: a new record, a change event from a monitor, a run reaching a terminal state, a delivery outcome. A webhook endpoint subscribes to the events you select and receives them as signed HTTP requests.

Each event envelope carries a schema version, the organization, the resource it concerns, the event time, and a unique event ID. The envelope is versioned on purpose — additive fields may appear over time, but a stored event is never silently reinterpreted.

Secrets never travel in an event body. Credentials, session material, and proxy details are references inside Ray9, and they stay there.

Signing

When you create an endpoint, Ray9 generates a signing secret and shows it to you once. Ray9 stores only an encrypted reference to it; there is no screen anywhere that will show it to you again.

Every delivery is signed with that secret. Verify the signature on your side before you act on the payload — an unsigned or badly signed request to your endpoint is not from Ray9, and treating it as though it were is how a webhook endpoint becomes an injection point.

Secrets rotate with an overlap window: the old secret and the new one are both valid for a period, so you can deploy the new one without dropping deliveries in between.

Idempotent event IDs and replay protection

Delivery is at-least-once. Networks time out after your server has already committed; a retry is the correct behaviour and it means you will occasionally see the same event twice.

The event ID is the idempotency key. It is semantic and stable: the same logical event always carries the same ID, no matter how many times it is delivered. Store it, check it, and ignore an event you have already processed.

Deliveries also carry replay protection, so an old, captured request cannot be replayed against your endpoint later and accepted as fresh.

Replaying an event from the Ray9 dashboard does not mint a new semantic event ID. A replay is the same event, delivered again — which is exactly what you want, because your idempotency check on the receiving side still works.

Verification and testing

Before an endpoint goes live, send a test event. It uses the exact production envelope, not a simplified fake — a test that does not look like the real thing is not a test.

Ray9 requires an acknowledged 2xx response to verify an endpoint. Anything else means the endpoint is not ready and is not treated as though it were.

Retries and the dead letter

A failed delivery retries with bounded exponential backoff. Bounded is the operative word: Ray9 retries a fixed number of times over a finite window and then stops. It does not hammer a broken endpoint indefinitely, and it does not give up after the first 500 either.

When retries are exhausted, the delivery moves to a dead-letter state. It is not lost. It is a durable record you can inspect and replay once the receiving side is fixed.

For every delivery you can see the event ID, each attempt, the response code, the latency, and when the next retry is due.

Handling deliveries well

A few things worth doing on your side:

• Verify the signature first. Before parsing, before dispatching, before anything.
• Check the event ID against what you have already processed. At-least-once delivery is a guarantee, not a bug.
• Return 2xx quickly and process asynchronously. A slow handler turns into a timeout, which turns into a retry, which turns into duplicate work.
• Do not infer ordering from arrival order. Use the event time in the envelope.

The alternative paths

Webhooks are one delivery mechanism, not the only one. The same records and change events can be exported as JSON or CSV, paged through on the public API, or read from an MCP client. Every route out uses the same underlying delivery abstraction, so future integrations — storage, spreadsheets, databases, queues, business tools — arrive as new destinations rather than as a parallel system with different semantics.