Webhook Delivery — Proposed Guide

Planned API — Reference Only

Webhook Delivery: Delivery status would describe transport acknowledgment, not completion of the consumer business workflow. A receiver can accept a…

Overview

Delivery status would describe transport acknowledgment, not completion of the consumer business workflow. A receiver can accept a message before its own processing finishes.

Key concepts

Track response class, attempt time and receiver acknowledgment separately from event state. Limit diagnostic payload retention.

Implementation considerations

No delivery is attempted here. Future contracts should distinguish temporary transport failure from an invalid subscription configuration.

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 Delivery",
  "delivery_id": "delivery_example_123",
  "event_id": "event_example_123",
  "status": "draft",
  "attempt_number": 1
}

Design review checklist

Document which organization owns the webhook delivery representation and which actor may view or change it.
Test the boundaries of delivery id, event id, status, attempt number 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
delivery_id	string	Stable fictional delivery reference; not a secret and not evidence that a resource exists.
event_id	string	Stable fictional event reference; not a secret and not evidence that a resource exists.
status	string	Proposed lifecycle value. Its meaning depends on the resource and must not be inferred from HTTP success.
attempt_number	integer	Delivery or processing attempt ordinal, separate from business-resource identity.

Webhook Retries

Webhooks & Events

Webhook Event Types