API ReferenceEvents
Send an event
Queue an event for delivery to every endpoint subscribed to its type.
Relay validates the event, stores it and returns right away with status queued. Delivery happens in the background.
Body parameters
The event type, such as invoice.paid. Up to 100 characters: letters, numbers, dots and underscores.
Your payload, up to 256 KB of JSON.
Only deliver to these endpoint IDs, even if others are subscribed.
ISO 8601 timestamp up to 7 days in the future to schedule the delivery.
Headers
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" }
}'const event = await relay.events.send({
type: "invoice.paid",
data: { invoice_id: "in_1042", amount: 4900, currency: "usd" },
idempotencyKey: "invoice-1042-paid",
});event = relay.events.send(
type="invoice.paid",
data={"invoice_id": "in_1042", "amount": 4900, "currency": "usd"},
idempotency_key="invoice-1042-paid",
)Response
{
"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.