GuidesCore concepts
Events
An event is something that happened in your application, sent once and delivered to every matching endpoint.
An event is a JSON message that describes something that happened in your application: an invoice was paid, a user signed up, a build finished. You send it to Relay once, and Relay delivers a copy to every endpoint subscribed to its type.
Anatomy of an event
{
"id": "evt_9fK2mLq81",
"type": "invoice.paid",
"created_at": "2026-10-14T09:31:12Z",
"data": {
"invoice_id": "in_1042",
"customer_id": "cus_77",
"amount": 4900,
"currency": "usd"
}
}Unique identifier, generated by Relay. Use it to deduplicate on your side.
A dot-separated name such as invoice.paid. Endpoints subscribe to types.
Your payload, up to 256 KB. Relay never changes it.
Naming event types
Use resource.action in the past tense, all lowercase. Consistent names make wildcard subscriptions useful.
| Good | Avoid |
|---|---|
invoice.paid | InvoicePaid |
user.created | new_user |
build.failed | build.fail |
Endpoints can subscribe to invoice.* to receive every invoice event, or * for everything.
Event lifecycle
queued → delivering → delivered
↘ failing → (retries) → delivered | failedAn event is delivered when every endpoint returned a 2xx. If at least one endpoint keeps failing after all retries, the event is failed and you can retry it manually.
Relay delivers at least once. In rare cases, such as a timeout after your server processed the request, an endpoint can receive the same event twice. Use the event id to make your handler idempotent.