> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runledger.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runledger.co/_mcp/server.

# Runledger event

POST 

Runledger posts a thin event to each enabled endpoint subscribed to its type. The body names the event type and the object it is about; fetch the object for its current state before acting. Deliveries follow Standard Webhooks: `webhook-id` (constant across retries, so use it to deduplicate), `webhook-timestamp` and `webhook-signature` (HMAC-SHA256, `v1,` prefix). Events arrive at least once and in no guaranteed order. Failed deliveries are retried with exponential backoff for 3 days. Respond with any `2xx` within 15 seconds.

Reference: https://docs.runledger.co/api-reference/webhooks/webhook-event

## Request

### Headers

- `webhook-id` (string, required) — Unique per event. The same on every retry.
- `webhook-timestamp` (string, required) — Unix seconds when this attempt was signed. Reject attempts older than 5 minutes.
- `webhook-signature` (string, required) — Space-separated `v1,<base64 HMAC-SHA256>` signatures over `webhook-id.webhook-timestamp.body`. Two are present while a secret rotates.

### Payload

- `id` (string, required)
- `object` ("webhook_event", required)
- `type` (enum, required) — New types may be added. Subscribe only to the ones you handle.
  - Allowed values: `customer.created`, `customer.updated`, `subscription.created`, `subscription.updated`, `subscription.renewed`, `subscription.past_due`, `subscription.canceled`, `credit_grant.created`, `credit_grant.expired`, `credit_grant.voided`, `balance.depleted`, `hold.expired`, `outcome_charge.created`, `outcome_charge.disputed`, `outcome_charge.confirmed`, `outcome_charge.locked`, `outcome_charge.reversed`, `reversal.created`, `dispute.created`, `dispute.decision_due`, `dispute.resolved`, `invoice.created`, `invoice.finalized`, `invoice.paid`, `invoice.payment_failed`, `checkout_session.completed`, `checkout_session.expired`, `export.ready`, `export.failed`, `payment.disputed`, `reconciliation.completed`, `reconciliation.breaks_found`, `test_clock.ready`, `rate_card.activated`, `catalog.price_changed`, `margin_guardrail.breached`, `simulation.completed`, `usage.threshold_reached`, `balance.low`, `spend_limit.threshold_reached`, `spend_limit.updated`, `auto_top_up.succeeded`, `auto_top_up.failed`, `auto_top_up.disabled`, `credit_grant.expiring`, `proposal.pending`, `topup_chargeback.threshold_exceeded`
- `api_version` (string, required)
- `related_object` (WebhookEventRelatedObject, required)
- `livemode` (boolean, required)
- `created_at` (datetime, required)
- `reason` (WebhookEventReason, optional) — What caused the event.
- `context` (WebhookEventContext, optional) — The fields that identify what a limit, window or purchase event is about, for events that don't name a stored object of their own. Fetch `related_object` for the current state.
- `delivery_status` (enum, optional) — `pending`: still being sent or retried. `succeeded`: every subscribed endpoint acknowledged it. `failed`: retries ran out for at least one endpoint.
  - Allowed values: `pending`, `succeeded`, `failed`
- `deliveries` (list of WebhookEventDeliveriesItems, optional) — Retrieve only. The last 10 attempts per endpoint.

## Types

### WebhookEventRelatedObject

- `id` (string, required)
- `object` (string, required)
- `url` (string, required) — The API path to fetch it.

### WebhookEventReason

What caused the event.

- `type` (enum, optional) — `request`: an API call. `rule`: a reversal rule, or a notification rule's lead time or threshold. `clock`: a window, horizon, deadline or period. `system`: Runledger, such as a reconciliation.
  - Allowed values: `request`, `rule`, `clock`, `system`
- `request_id` (string, optional)
- `idempotency_key` (string, optional) — The idempotency key of the causing request, to match events to your own submissions.
- `notification_rule` (string, optional) — When a notification rule's lead time or threshold made the event: the rule (`nr_...`). Such an event goes to the rule's endpoint alone, not to the endpoints subscribed to its type.

### WebhookEventContext

The fields that identify what a limit, window or purchase event is about, for events that don't name a stored object of their own. Fetch `related_object` for the current state.

- `customer` (string, optional)
- `member_id` (string, optional)
- `team_id` (string, optional)
- `pool` (string, optional)
- `allowance` (string, optional) — The allowance key.
- `spend_limit` (string, optional) — The spend limit ID.
- `threshold` (string, optional) — The `alert_at` value that was reached, as a decimal from 0 to 1.
- `window_start` (datetime, optional)
- `resets_at` (datetime, optional)

### WebhookEventDeliveriesItems

- `webhook_endpoint` (string, required)
- `attempted_at` (datetime, required)
- `succeeded` (boolean, required)
- `status_code` (integer, optional)
- `duration_ms` (integer, optional)