> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riverside.fm/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Receive real-time HTTP callbacks when events happen in your Riverside account.

Webhooks let Riverside push events to your systems in real time. Instead of polling the API, you register an HTTPS endpoint (a **subscription**) and Riverside sends a signed `POST` request to it whenever a subscribed event occurs — for example when a webinar starts or a registrant signs up.

## How it works

1. **Subscribe** — create a subscription with your endpoint URL and the event types you want. Riverside returns a **signing secret** (shown only once).
2. **Receive** — when a subscribed event happens, Riverside `POST`s a JSON [event envelope](#the-event-envelope) to your URL, signed with your secret.
3. **Verify** — validate the signature and timestamp headers before trusting the payload. See [Verifying Signatures](/webhooks/verifying-signatures).
4. **Acknowledge** — respond with any `2xx` status promptly. Non-`2xx` responses, timeouts, and network errors are [retried](/webhooks/delivery-and-retries).

## The event envelope

Every delivery — regardless of event type — shares the same outer JSON shape. The event-specific fields live inside `data`.

```json theme={null}
{
  "id": "evt_9f8c2a1b7d3e4f56",
  "event": "webinar.started",
  "event_ts": 1752595283,
  "account_id": "acc_1a2b3c4d",
  "data": { },
  "delivery_attempt": 1
}
```

| Field              | Type    | Description                                                                                                       |
| :----------------- | :------ | :---------------------------------------------------------------------------------------------------------------- |
| `id`               | string  | Unique identifier for this event. **Deduplicate on this value** — the same event may be delivered more than once. |
| `event`            | string  | The wire event type, e.g. `webinar.started`. See [Event Types](/webhooks/event-types).                            |
| `event_ts`         | integer | Unix timestamp (seconds) of when the event occurred — not when it was delivered.                                  |
| `account_id`       | string  | The Riverside account the event belongs to.                                                                       |
| `data`             | object  | The event-specific public payload. Its shape depends on `event` — see [Event Types](/webhooks/event-types).       |
| `delivery_attempt` | integer | 1 on the first attempt; increments on each [retry](/webhooks/delivery-and-retries).                               |

## Delivery guarantees

* **At-least-once.** A successful delivery is any `2xx` response. On failure Riverside retries on a backoff schedule; a single event can therefore be delivered more than once. Always dedupe on `id`.
* **Not ordered.** Events are not guaranteed to arrive in the order they occurred. Use `event_ts` if ordering matters to you.
* **HTTPS only.** Endpoints must be publicly reachable over HTTPS. Redirects are **not followed** — a `3xx` response is treated as a failed attempt.
* **Signed.** Every request carries an HMAC signature and timestamp so you can verify authenticity and guard against replay.

## Next steps

<CardGroup cols={2}>
  <Card title="Event Types" icon="webhook" href="/webhooks/event-types">
    The catalog of events you can subscribe to and their payloads.
  </Card>

  <Card title="Verifying Signatures" icon="webhook" href="/webhooks/verifying-signatures">
    Authenticate incoming deliveries.
  </Card>

  <Card title="Delivery & Retries" icon="webhook" href="/webhooks/delivery-and-retries">
    Retry schedule, auto-disable, and replay.
  </Card>
</CardGroup>