Webhook delivery and retries

Ledgerline delivers webhooks at least once. If your endpoint is down or slow, we keep trying for almost two days. This page describes what counts as success, the retry schedule, what happens when an endpoint keeps failing and how to replay events you missed.

What counts as success

A delivery succeeds when your endpoint returns any 2xx status within 10 seconds. Everything else is a failure and is retried:

• A 3xx, 4xx or 5xx response. Ledgerline does not follow redirects.
• A timeout, including a connection that opens and then stalls.
• A TLS error, such as an expired or mismatched certificate.
• A connection that is refused or reset.

The response body is ignored, though the first 1 KB is kept in the delivery log to help you debug.

Retry schedule

Ledgerline makes up to 8 attempts in total: the first delivery and seven retries with increasing delays.

After the eighth failure the delivery is marked failed and Ledgerline stops. Each retry re-signs the payload with a fresh timestamp, so signature verification keeps working, and the event.id stays the same.

Disabled endpoints

If every delivery to an endpoint fails for 72 hours in a row, Ledgerline disables the endpoint. Account owners get a dashboard notice and an event of type webhook_endpoint.disabled is recorded in the audit log. Events keep being generated and are stored, but they are not sent.

To recover:

1. Fix the cause. Check the delivery log for the status code or error.
2. Re-enable the endpoint in Developers > Webhooks, or call POST /v1/webhook_endpoints/{id} with status=enabled.
3. Replay the events you missed.

Replaying events

Events and their delivery logs are kept for 30 days. Within that period you can redeliver any event:

curl -X POST https://api.ledgerline.dev/v1/events/evt_01JA7E2Q9R/redeliver \
  -H "Authorization: Bearer $LEDGERLINE_API_KEY" \
  -H "Idempotency-Key: 5c0e2b8d-1a7f-4e63-9d2b-6f8a3c1e0d47" \
  -d endpoint_id=whe_01J9ZV4T3B

In the dashboard, select an event and choose Resend. To catch up after an outage, list events with GET /v1/events?created_after=...&type=payout.paid and process any you do not have. Your handler must deduplicate on event.id, since a replay is indistinguishable from a normal delivery.

Ordering

Delivery order is not guaranteed. Retries, parallel delivery and network paths mean a later event can arrive first. Design handlers so that applying the same event twice, or applying events in a different order, leads to the same state:

• Store the latest status together with the object's updated_at and ignore older updates.
• Treat the event as a notification and fetch the current object when order matters.

Concurrency and rate

Ledgerline delivers to one endpoint with up to 10 concurrent requests. If you need strict sequencing, enqueue each event on receipt and process it from a single worker.

Monitoring deliveries

The delivery log for each endpoint shows the attempt number, response status, latency and the response snippet for 30 days. Set up an alert on your own side for a growing gap between event creation time and handling time, since that is the earliest sign of trouble.

Security

All retries carry a valid signature. Reject anything that fails verification with a 400 instead of a 2xx, otherwise Ledgerline will consider it delivered.

For endpoint setup and event types see the webhooks overview. The general guidance on retrying your own API calls is in Retries and backoff.