Payload Retention

Why You Would Use This

HookBridge stores webhook payloads so they can be inspected, replayed, and debugged. Payloads are retained for a limited time based on your plan. Understanding retention behavior helps you plan your replay and debugging workflows.

How It Works

• When a webhook is sent, HookBridge stores the payload durably before queuing it for delivery.
• Payloads are retained for a period determined by your plan.
• After the retention period expires, the payload is automatically cleaned up.
• Message metadata (status, timestamps, attempt history, response codes, errors) is kept longer than payloads and remains visible after the payload is removed.

What Happens After Retention Expires

• The payload is deleted. It cannot be recovered.
• The message record and all metadata remain visible in the console and API.
• Attempting to replay a message whose payload has expired returns a 410 Gone response with the error code RETENTION_EXPIRED.
• If the payload has already been cleaned up by the automatic process, a replay attempt returns PAYLOAD_UNAVAILABLE (also 410 Gone).

Per-Message Retention Override

When sending a webhook, you can optionally set retention_hours to specify a shorter retention period for that individual message. The value cannot exceed your plan’s maximum retention.

curl -X POST https://send.hookbridge.io/v1/webhooks/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_id": "YOUR_ENDPOINT_ID",
    "payload": {"event": "order.created"},
    "retention_hours": 24
  }'

If omitted, the message uses your plan’s default retention period.

Operational Tips

• Replay failed messages promptly — do not wait until retention expires.
• Use exports to preserve delivery records for audit or compliance before payloads age out.
• If you need longer retention, consider upgrading your plan.