Retries & Delivery Logs

BeeL. automatically retries webhook deliveries that fail due to network errors or non-2xx HTTP responses. You can also inspect the delivery history and trigger manual retries from the dashboard or the API.

Retry Policy

Backoff Schedule

If all 5 attempts fail, no further automatic retries occur. You can still trigger a manual retry from the dashboard or API at any time.

What Triggers a Retry

Delivery Logs

BeeL. keeps a log of the last 50 delivery attempts per subscription. Each log entry records:

• Delivery timestamp and duration
• HTTP status code and response body
• All request headers sent (including BeeL-Signature, BeeL-Event-Id, BeeL-Delivery-Id, BeeL-Event)
• The full JSON payload that was sent
• The attempt number
• Error description (for failed deliveries)

View delivery logs

GET /v1/accounts/{account_id}/webhooks/{webhook_id}/deliveries — webhooks:read. Newest first, paginated. Query params: page, limit, event_type (only deliveries of one event type) and event_id (only deliveries of one event — use it to follow every attempt on a single event without paging through the whole history).

curl "https://app.beel.es/api/v1/accounts/{account_id}/webhooks/3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/deliveries?event_type=verifactu.status.updated" \
  -H "Authorization: Bearer beel_sk_live_xxx"

{
  "success": true,
  "data": {
    "deliveries": [
      {
        "id": "8ee6b023-c4e5-482e-93ca-dc66da2f9cb5",
        "subscription_id": "3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
        "webhook_event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "event_type": "verifactu.status.updated",
        "attempt_number": 1,
        "http_status": 200,
        "success": true,
        "duration_ms": 142,
        "response_body": "OK",
        "error_message": null,
        "request_headers": {
          "BeeL-Signature": "t=1741362026,v1=3c4f7a2e...",
          "BeeL-Event": "verifactu.status.updated",
          "BeeL-Event-Id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "BeeL-Delivery-Id": "8ee6b023-c4e5-482e-93ca-dc66da2f9cb5",
          "Idempotency-Key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        },
        "payload": "{\"id\":\"a1b2c3d4...\",\"type\":\"verifactu.status.updated\",...}",
        "delivered_at": "2026-03-07T16:20:26Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1 }
  }
}

Reading a log entry

Every field of the entry is described in List webhook delivery logs. What the schema cannot tell you is which of them answer which question:

• "Is this the same event I already saw?" — webhook_event_id groups every attempt at one logical event and matches the BeeL-Event-Id header; id identifies this attempt and matches BeeL-Delivery-Id. Deduplicate on the former, correlate your server logs with the latter.
• "Did my endpoint refuse it, or never see it?" — http_status is null when the connection itself failed (DNS, timeout, TLS), and error_message says which. A populated http_status means your server answered and the payload reached it.
• "Can I replay it myself?" — request_headers and payload hold the exact bytes and signature that were sent, so you can re-run your verification offline against a delivery that failed, without waiting for the next one.

Manual Retry

POST /v1/accounts/{account_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/retry — webhooks:write. Triggers a retry for any delivery, successful or not:

curl -X POST \
  "https://app.beel.es/api/v1/accounts/{account_id}/webhooks/3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/deliveries/8ee6b023-c4e5-482e-93ca-dc66da2f9cb5/retry" \
  -H "Authorization: Bearer beel_sk_live_xxx" \
  -H "Idempotency-Key: $(uuidgen)"

This uses the original payload and generates a new signature with a fresh timestamp. A new delivery log entry is created with the result.

Endpoint Requirements

To ensure reliable delivery, your endpoint should:

• Respond within 10 seconds — BeeL. does not wait longer
• Return 2xx immediately and process the event asynchronously if needed
• Return 5xx if you are temporarily unable to process (triggers a retry)
• Not return 4xx unless the payload itself is the problem

// ✅ Good: acknowledge immediately, process async
app.post('/webhooks/beel', async (req, res) => {
  res.status(200).send('OK'); // respond first
  await queue.push(req.body); // process later
});

// ❌ Bad: synchronous processing blocks the response
app.post('/webhooks/beel', async (req, res) => {
  await processEventSynchronously(req.body); // may exceed 10s timeout
  res.status(200).send('OK');
});