> ## Documentation Index
> Fetch the complete documentation index at: https://relay-demo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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.

![Diagram of one invoice.paid event sent to Relay and delivered to the billing service, subscribed to invoice.\*, and the analytics pipeline, subscribed to all events, but not to the Slack alerts endpoint, subscribed only to customer.created.](https://mintcdn.com/relay-demo/g4EzaOdLYNrmsxJ6/images/event-fanout.png?fit=max\&auto=format\&n=g4EzaOdLYNrmsxJ6\&q=85\&s=9bc89d4cef0e0adab534a52e13823a17)

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:

```json theme={null}
{
  "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](https://relay-demo.mintlify.site/rate-limits.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.