Webhooks - Mintlify Starter Kit

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.

GET /v1/tenants/webhooks

Authentication

Authorization: Bearer <jwt>

Example

curl https://api.eldrstream.com/v1/tenants/webhooks \
  -H "Authorization: Bearer <jwt>"

Response

[
  {
    "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.

PUT /v1/tenants/webhooks

Authentication

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

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)

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

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

[
  {
    "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)

Body

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

{
  "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.

​List webhooks

​Authentication

​Example

​Response

​Update webhooks

​Authentication

​Request body

​Example — set a single webhook

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

​Example — remove all webhooks

​Response

​Status codes

​What EldrStream sends to your endpoint

​Headers

​Body

​Expected response

​Timeout

List webhooks

Authentication

Example

Response

Update webhooks

Authentication

Request body

Example — set a single webhook

Example — set two webhooks (Business plan and above)

Example — remove all webhooks

Response

Status codes

What EldrStream sends to your endpoint

Headers

Body

Expected response

Timeout