Webhook API Documentation

Document webhook-based integrations with event definitions, HMAC signature verification, delivery guarantees, retry policies, and consumer guidance. The structured webhook editor captures what architects need to express about push-based event notifications.

February 25, 2026

Webhooks are HTTP callback mechanisms where a system pushes event notifications to a subscriber's URL when specific events occur. They are ubiquitous in modern platforms: Stripe, GitHub, Slack, Twilio, SendGrid, Shopify, and virtually every SaaS product offers webhooks as the primary integration mechanism. The dedicated webhook documentation workflow captures security verification, delivery guarantees, retry policies, and event definitions in a structured, publishable format.

Core Concepts

Webhook API documentation is organised around a root API definition and individual event definitions that describe each webhook event type.

Webhook API Definition

The root definition captures the base URL, security configuration (HMAC, mTLS, shared secrets), delivery guarantees, retry policies, circuit breaker settings, subscription management endpoints, and consumer guidance. One definition per webhook provider.

Webhook Event Definitions

Each event type (order.created, payment.processed, inventory.updated) is documented with its trigger conditions, source system, headers, payload schema reference, and concrete JSON examples. Events are grouped by category for navigation.

Security Verification

Document how webhook deliveries are authenticated: HMAC-SHA256 signatures, asymmetric key verification, shared secrets, mTLS, bearer tokens, or basic authentication. Include the header name, signature prefix, encoding format, and secret management guidance.

Delivery and Retry

Capture retry policies with specific intervals, backoff strategies, timeout thresholds, dead letter queues, and circuit breaker configuration. Document whether delivery is at-most-once, at-least-once, or exactly-once.

What Architects Document

Webhook documentation addresses the questions that consuming teams and integration architects ask when building against a webhook provider.

Security Verification Methods

NeoArc supports documenting multiple verification method types that cover the full spectrum of webhook security patterns.

Method	Description	Common Usage
HMAC	Hash-based message authentication with SHA-256, SHA-1, or SHA-512	Stripe, GitHub, Shopify, Slack
Asymmetric	RSA-SHA256, ECDSA-SHA256, or Ed25519 public key verification	Twilio, Svix
Shared Secret	Static secret sent in a header for simple verification	Basic integrations
Mutual TLS	Client certificate verification at the transport layer	Enterprise and financial APIs
Bearer Token	Pre-shared token sent in the Authorization header	Simple SaaS integrations
Basic Auth	Username and password in the Authorization header	Legacy systems
None	No verification (documented with security implications)	Development and testing only

Delivery Configuration

Webhook reliability depends on clear documentation of retry behaviour, timeouts, and failure handling.

Timeout

Maximum seconds the provider waits for a response before marking delivery as failed. Typically 30 seconds. Consumers should process events asynchronously and respond quickly.

Retry Policy

Number of retries, specific intervals (e.g. 1min, 5min, 15min, 1hr, 4hr), and backoff strategy (fixed, linear, exponential). Consumers need this to size their monitoring windows.

Dead Letter Queue

Whether permanently failed events are retained, for how many days, and whether replay is supported. Critical for consumers who need to recover from extended outages.

E-Commerce Webhooks Example

The following example demonstrates a complete webhook API specification for an e-commerce platform with four event types across three categories.

Webhook API

The root API definition for the e-commerce webhooks, including security, delivery, and registration configuration.

Order Events

Order lifecycle events fire as orders progress from creation through fulfilment.

Payment Events

Payment events fire when the payment gateway processes a capture or decline.

Inventory Events

Inventory events fire when stock levels change for any reason: sales, returns, or manual adjustments.

Consumer Guidance

Well-documented webhook APIs include clear guidance for consuming teams on how to build reliable integrations.

Storage

A webhook API lives in a single .projection.json file with profileType: 'api' and apiType: 'webhook'. The projection can sit wherever you choose to put it in the workspace.

Comparison with Async Event APIs

Webhooks and async event APIs serve similar purposes but differ in transport, consumer model, and operational characteristics.

Aspect	Webhooks	Async Event APIs
Transport	HTTP callbacks to subscriber URLs	Message brokers (Kafka, AMQP, MQTT)
Consumer Model	Push to registered endpoints	Pull from broker or push via consumer groups
Registration	Subscriber registers a URL	Consumer subscribes to a topic/queue
Security	HMAC signatures, shared secrets	SASL, mTLS, OAuth2 at broker level
Ordering	Approximate within aggregate	Partition-level ordering (Kafka)
Replay	Provider-dependent (dead letter queue)	Consumer offsets and log retention
When to Use	SaaS integrations, simple event notifications	High-throughput, complex event routing, stream processing