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

# Webhooks

> Configure the endpoints EldrStream delivers events to

Webhooks are the HTTPS endpoints in your own infrastructure that eldrStream delivers events to. You register one or more webhook URLs in your account; EldrStream POSTs each event to every registered endpoint.

***

## List webhooks

Returns your currently configured webhook endpoints.

```text theme={null}
GET /v1/tenants/webhooks
```

### Authentication

```text theme={null}
Authorization: Bearer <jwt>
```

### Example

```bash theme={null}
curl https://api.eldrstream.com/v1/tenants/webhooks \
  -H "Authorization: Bearer <jwt>"
```

### Response

```json theme={null}
[
  {
    "id": "a3f8bc1d2e-0",
    "url": "https://example.com/hooks/eldrstream",
    "name": "Production Webhook"
  }
]
```

| Field  | Description                                                |
| ------ | ---------------------------------------------------------- |
| `id`   | Unique identifier for this webhook entry                   |
| `url`  | The registered endpoint URL                                |
| `name` | Display name (as provided when the webhook was registered) |

***

## Update webhooks

Replaces your entire webhook configuration. The request body must contain the complete desired list of webhook endpoints. Omitting a previously registered URL removes it.

```text theme={null}
PUT /v1/tenants/webhooks
```

### Authentication

```text theme={null}
Authorization: Bearer <jwt>
```

### Request body

An array of webhook objects. The maximum number of webhooks depends on your plan:

| Plan       | Max webhooks |
| ---------- | ------------ |
| Free       | 1            |
| Pro        | 1            |
| Business   | 2            |
| Enterprise | 3            |

Each webhook object:

| Field         | Type   | Required | Description                                                    |
| ------------- | ------ | -------- | -------------------------------------------------------------- |
| `webhook_url` | string | Yes      | The fully qualified HTTPS URL EldrStream should POST events to |
| `name`        | string | No       | A human-readable label for this endpoint                       |

### Example — set a single webhook

```bash theme={null}
curl -X PUT https://api.eldrstream.com/v1/tenants/webhooks \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "webhook_url": "https://example.com/hooks/eldrstream",
      "name": "Production Webhook"
    }
  ]'
```

### Example — set two webhooks (Business plan and above)

```bash theme={null}
curl -X PUT https://api.eldrstream.com/v1/tenants/webhooks \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "webhook_url": "https://example.com/hooks/primary",
      "name": "Primary"
    },
    {
      "webhook_url": "https://example.com/hooks/secondary",
      "name": "Secondary"
    }
  ]'
```

### Example — remove all webhooks

```bash theme={null}
curl -X PUT https://api.eldrstream.com/v1/tenants/webhooks \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '[]'
```

### Response

Returns the saved webhook list (same format as the List response).

```json theme={null}
[
  {
    "webhook_url": "https://example.com/hooks/eldrstream",
    "name": "Production Webhook"
  }
]
```

### Status codes

| Status             | Meaning                                      |
| ------------------ | -------------------------------------------- |
| `200 OK`           | Webhooks updated successfully                |
| `400 Bad Request`  | Provided more webhooks than your plan allows |
| `401 Unauthorized` | Missing or invalid JWT                       |

***

## What EldrStream sends to your endpoint

For every event, EldrStream sends an HTTP `POST` request to your registered URL with the following headers and body:

### Headers

| Header                 | Description                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `Content-Type`         | `application/json`                                                                    |
| `Eldrstream-Event-Id`  | The unique event ID (e.g. `evt_01J8ZXQY5H...`)                                        |
| `Eldrstream-Signature` | Ed25519 signature for payload verification (see [Security & Signing](../security.md)) |

### Body

The JSON body contains the decrypted event payload as you originally submitted it, along with envelope metadata:

```json theme={null}
{
  "eventId": "evt_01J8ZXQY5H4KCZP3M2R...",
  "tenantId": "a3f8bc1d2e",
  "ingestionTimestamp": "2025-01-15T10:30:00.000Z",
  "payload": {
    "event_type": "order.created",
    "order_id": "ORD-1001",
    "amount": 4999
  }
}
```

### Expected response

Return any `2xx` status code to acknowledge receipt. EldrStream treats `4xx` responses (other than `429`) as permanent failures and will not retry. `5xx` and `429` responses trigger the retry schedule.

### Timeout

EldrStream waits up to **10 seconds** for a response from your endpoint. Requests that exceed this deadline are treated as retryable failures.