Skip to content
RelayDocumentation

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

invoice.paid
{
  "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"
  }
}
idstring

Unique identifier, generated by Relay. Use it to deduplicate on your side.

typestring

A dot-separated name such as invoice.paid. Endpoints subscribe to types.

dataobject

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.

GoodAvoid
invoice.paidInvoicePaid
user.creatednew_user
build.failedbuild.fail

Endpoints can subscribe to invoice.* to receive every invoice event, or * for everything.

Event lifecycle

queued → delivering → delivered
                    ↘ failing → (retries) → delivered | failed

An 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.