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

# Webhooks overview

> Receive real-time events from Endl over signed webhooks, or poll for them

Register subscriptions for the events you care about. When a matching event occurs, Endl delivers it — either by pushing it to your endpoint or by making it available for you to poll.

## Delivery modes

<Columns cols={2}>
  <Card title="PUSH" icon="paper-plane">
    Endl sends each event to your HTTPS endpoint as a signed `POST`, with retries. You host a receiver. This is the default.
  </Card>

  <Card title="PULL" icon="inbox-in">
    Endl delivers nothing. You poll the [event feed](/webhooks/pull-feed) and checkpoint a cursor.
  </Card>
</Columns>

## Base URL

| Environment | Base URL                  |
| ----------- | ------------------------- |
| QA          | `https://qa-api.endl.xyz` |
| Production  | Provided at onboarding    |

All webhook endpoints live under `/api/v0`.

## Quickstart

<Steps>
  <Step title="Authenticate">
    Send `X-API-KEY` and `X-API-SECRET` on every request. See [Authentication](/webhooks/authentication).
  </Step>

  <Step title="Create a subscription">
    Register your receiver URL and the event types you want. The response returns your signing secret **once** — store it before moving on.

    ```bash theme={null}
    curl -X POST https://qa-api.endl.xyz/api/v0/webhooks/subscriptions \
      -H "X-API-KEY: $ENDL_API_KEY" -H "X-API-SECRET: $ENDL_API_SECRET" \
      -H "Content-Type: application/json" \
      -d '{
        "target": "https://api.acme.com/webhooks/endl",
        "eventFilter": ["payout.completed", "payout.failed"]
      }'
    ```
  </Step>

  <Step title="Receive and verify">
    Endl `POST`s each event with an `X-WEBHOOK-SIGNATURE` header. [Verify it](/webhooks/signature-verification) before trusting the payload.
  </Step>

  <Step title="Inspect deliveries">
    Every attempt is recorded. [List them, drill into one, or retry](/webhooks/deliveries).
  </Step>
</Steps>

## Conventions

<Info>
  Your identity comes from your API key, so you only ever see and manage your own resources. Every response is wrapped in [the standard envelope](/webhooks/errors). Timestamps are ISO-8601 UTC with three fraction digits — `2026-09-02T12:34:56.789Z`.
</Info>

<Note>
  **Phase 1.** Subscriptions are `PUSH` or `PULL`. `SQS` and `SSE` modes are reserved but not yet available; requesting one returns `422`.
</Note>

## Next steps

<Columns cols={2}>
  <Card title="Verify signatures" icon="shield-check" href="/webhooks/signature-verification">
    Prove a delivery came from Endl before acting on it.
  </Card>

  <Card title="Manage subscriptions" icon="rss" href="/webhooks/subscriptions">
    Create, update, pause, and rotate secrets.
  </Card>

  <Card title="Inspect deliveries" icon="list-check" href="/webhooks/deliveries">
    See every attempt, and retry the ones that failed.
  </Card>

  <Card title="Event types" icon="table-list" href="/webhooks/reference">
    The event catalogue, enums, and limits.
  </Card>
</Columns>