Webhook Retries — Proposed Guide

Planned API — Reference Only

Webhook Retries: Retries could redeliver a previously created event after an unsuccessful attempt. Consumers must recognize the original event rather than…

Overview

Retries could redeliver a previously created event after an unsuccessful attempt. Consumers must recognize the original event rather than process every delivery as a new financial fact.

Key concepts

Deduplicate by event id and record attempt ids separately. Use bounded retry scheduling and an explicit terminal state.

Implementation considerations

No retry cadence or maximum attempts is promised. An eventual manual replay needs the same authorization and deduplication checks.

Illustrative data model

This local fixture shows a possible representation for the concepts above. It is not an endpoint response, production configuration or a claim that the described capability is implemented.

JSON fixture

Fictional concept fixture

{
  "reference_only": true,
  "topic": "Webhook Retries",
  "event_id": "event_example_123",
  "delivery_id": "delivery_example_123",
  "attempt_number": 1,
  "retry_after": 10
}

Design review checklist

Document which organization owns the webhook retries representation and which actor may view or change it.
Test the boundaries of event id, delivery id, attempt number, retry after using synthetic values, including missing or inconsistent references.
Before future implementation, obtain an approved contract and review failure behavior. This documentation does not authorize production activation.

Proposed data types

Illustrative field dictionary
Name	Type	Description
event_id	string	Stable fictional event reference; not a secret and not evidence that a resource exists.
delivery_id	string	Stable fictional delivery reference; not a secret and not evidence that a resource exists.
attempt_number	integer	Delivery or processing attempt ordinal, separate from business-resource identity.
retry_after	integer	Illustrative wait in seconds, not a published retry or service guarantee.

Webhook Security

Webhooks & Events

Webhook Delivery