Skip to content
RelayDocumentation

API ReferenceEvents

Send an event

Queue an event for delivery to every endpoint subscribed to its type.

POST/v1/events

Relay validates the event, stores it and returns right away with status queued. Delivery happens in the background.

Body parameters

typestringrequired

The event type, such as invoice.paid. Up to 100 characters: letters, numbers, dots and underscores.

dataobjectrequired

Your payload, up to 256 KB of JSON.

endpointsstring[]

Only deliver to these endpoint IDs, even if others are subscribed.

deliver_atstring

ISO 8601 timestamp up to 7 days in the future to schedule the delivery.

Headers

Idempotency-Keystring

A unique key for this event. Repeating a request with the same key within 24 hours returns the original event. See Idempotency.

Request

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

Response

201 Created
{
  "id": "evt_9fK2mLq81",
  "object": "event",
  "type": "invoice.paid",
  "status": "queued",
  "created_at": "2026-10-14T09:31:12Z",
  "endpoints_matched": 3,
  "data": { "invoice_id": "in_1042", "amount": 4900, "currency": "usd" }
}

Batch sending

Send up to 100 events in one request to POST /v1/events/batch with { "events": [...] }. Each item accepts the same fields as above plus its own idempotency_key. The response lists the created events in the same order.