Send events

Send an event once and Relay delivers it to every endpoint that subscribed to its type.

An event is something that happened in your app, with a type and a payload:

curl https://api.relay.example/v1/events \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Idempotency-Key: invoice-inv_123-paid" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice.paid",
    "data": {"invoice_id": "inv_123", "customer_id": "cus_88", "amount": 4900, "currency": "usd"}
  }'

Relay answers 202 Accepted once the event is stored. Delivery happens after that, so the response doesn’t wait for your endpoints.

Endpoints and subscriptions

An endpoint is a URL that receives webhooks. Each endpoint subscribes to the event types it wants. When you send an event, Relay creates one delivery for each endpoint whose subscriptions match, and tracks and retries each delivery on its own.

One invoice.paid event becomes two deliveries: billing and analytics subscribed to it, Slack alerts did not.

Subscription	Matches
invoice.paid	That type only.
invoice.*	Every type that starts with invoice..
*	Every event.

Event types

Name types resource.action in lowercase, such as invoice.paid or customer.created. Relay doesn’t need you to register types first; the dashboard lists every type it has seen.

Payloads

data is any JSON object up to 256 KB, and Relay delivers it unchanged inside this envelope:

{
  "id": "evt_2Lk9xQ",
  "type": "invoice.paid",
  "created": 1729600000,
  "data": { "invoice_id": "inv_123", "customer_id": "cus_88", "amount": 4900, "currency": "usd" }
}

Keep payloads small and stable. Send ids and the fields a receiver needs to act; a receiver that needs more can fetch it from your API. Add fields freely, but don’t rename or remove them: endpoints you don’t control may depend on them.

Batches

Send up to 100 events in one request with POST /v1/events/batch. Each event in a batch can have its own idempotency_key. See Rate limits.