2026-09-26 · 8 min read
- openapi
- webhooks
- api
OpenAPI 3.1 adds a top-level webhooks map for provider-initiated requests that are not tied to one specific inbound operation. Each named entry contains a Path Item Object describing the request a subscriber can receive.
The description is a contract, not a delivery engine or subscriber registry. Runtime destination validation, authentication, retries, observability, and lifecycle policy still need explicit implementation.
Choose a stable event vocabulary
Name webhook entries by durable business events rather than internal jobs or temporary endpoints. Define event ownership, compatibility expectations, deprecation, and how a subscriber selects event types.
- Use one documented meaning per event name.
- Include a stable event identifier.
- Define event occurrence and delivery timestamps.
- Separate test events from production semantics.
Specify the complete HTTP exchange
For each Path Item, define method, required headers, media type, request schema, examples, security scheme, and accepted receiver responses. State timeout behavior and whether the provider reads a response body.
Keep examples synthetic and free of credentials or customer data. Use required fields sparingly, explain nullability and omission, and provide a forward-compatibility rule for unknown properties and event versions.
Make authenticity verifiable
Specify the exact signed bytes, signature encoding, algorithm policy, key identifier, timestamp input, tolerance, replay cache, and secret or key rotation procedure. Receivers should verify the original bytes before parsing or reserializing the body.
Plan dual-key or overlapping verification during rotation and distinguish invalid signatures from unknown key identifiers. Do not embed long-lived shared secrets in the OpenAPI document or examples.
Control destinations and delivery
Validate subscriber URLs on registration and again before delivery. Restrict schemes, hosts, ports, DNS and IP ranges, redirects, timeouts, response sizes, and network egress. Scope credentials and tenant data to the intended subscriber.
Define retry delays, maximum attempts, terminal outcomes, ordering guarantees, duplicate behavior, and manual replay policy. Receivers should implement an idempotent inbox keyed by event identity.
Verify the specification pipeline
Use Flashman's YAML/JSON converter for the OpenAPI source, JSON formatter for event fixtures, URL tool for harmless destinations, diff for generated artifacts, and hash tool for fixture identity.
Test OpenAPI 3.1 validation, reference bundling, documentation renderers, SDK or stub generators, gateways, required headers, signature fixtures, schema evolution, retries, duplicates, redirects, DNS changes, receiver downtime, secret rotation, and safe logs.