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

# Event Ingestion

> Send events into EldrStream for delivery to your webhooks

Use the ingestion endpoint to publish events from your application. eldrStream encrypts the payload, queues it for delivery, and dispatches it to all your registered webhook endpoints.

***

## Send an event

```text theme={null}
POST /v1/ingest
```

### Authentication

This endpoint uses your **API key**, not a JWT session token.

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

### Request body

| Field     | Type   | Required | Description                                                                                 |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------- |
| `payload` | object | Yes      | Any valid JSON object. No schema restrictions.                                              |
| `eventId` | string | No       | A client-supplied identifier. If omitted, EldrStream generates a ULID-based ID (`evt_...`). |

### Example

```bash theme={null}
curl -X POST https://api.eldrstream.com/v1/ingest \
  -H "Authorization: Bearer eldr_sk_9f4c2a..." \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "event_type": "payment.completed",
      "transaction_id": "txn_9981",
      "amount_ngn": 50000,
      "customer_id": "cust_001"
    }
  }'
```

### Supplying your own event ID

```bash theme={null}
curl -X POST https://api.eldrstream.com/v1/ingest \
  -H "Authorization: Bearer eldr_sk_9f4c2a..." \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "my-internal-id-1234",
    "payload": {
      "event_type": "user.signup",
      "user_id": "user_789"
    }
  }'
```

### Response

```json theme={null}
{
  "status": "accepted",
  "eventId": "evt_01J8ZXQY5H4KCZP3M2R..."
}
```

| Field     | Description                                                                                  |
| --------- | -------------------------------------------------------------------------------------------- |
| `status`  | Always `"accepted"` on success                                                               |
| `eventId` | The unique identifier assigned to this event. Use this to look up or replay the event later. |

### Status codes

| Status                      | Meaning                                                 |
| --------------------------- | ------------------------------------------------------- |
| `202 Accepted`              | Event received and queued for delivery                  |
| `401 Unauthorized`          | Missing or invalid API key                              |
| `500 Internal Server Error` | Ingestion failure — safe to retry with the same payload |

***

## Notes on delivery

* A `202 Accepted` response guarantees EldrStream has received your event. Delivery to your webhook is asynchronous.
* Events are delivered to all configured webhook endpoints in parallel.
* Failed deliveries are retried automatically. See [Core Concepts — Retries](../core-concepts.md#retries) for the retry schedule.
* If no webhook endpoints are configured, the event is accepted and stored but not dispatched until you add a webhook.
* You can track the final delivery outcome using the [Events API](./events.md).