2026-09-26 · 6 min read · Rahul Chitturi
- openapi
- webhooks
- api
OpenAPI 3.1 can describe provider-initiated webhook requests in a top-level webhooks map. Each entry names an event contract with a Path Item Object, but the map key is an identifier rather than the subscriber's runtime destination.
Documentation breaks when teams model a webhook as an ordinary inbound path, confuse it with a callback expression, or assume code generators and validators support every OpenAPI 3.1 feature.
Separate contract from registration
Record the OpenAPI version, webhook key, HTTP method, request schema, headers, security scheme, response expectations, event identifier, and the separate process that validates and stores subscriber URLs.
- Use stable event names for webhook map keys.
- Define exact media types and required headers.
- Keep runtime destination policy outside examples.
- Document delivery and response timeout semantics.
Specify secure delivery
Define signature input bytes, algorithm, key identification, timestamp tolerance, replay protection, retries, ordering, duplicate handling, and secret rotation. Receivers must verify the unmodified request body before parsing transforms it.
Validate subscriber destinations against scheme, host, port, DNS and IP policy on registration and delivery. Apply redirect limits, timeouts, response-size caps, egress controls, and tenant isolation.
Compare tooling with the wire
Use Flashman's YAML/JSON converter for the specification, JSON formatter for synthetic events, URL tool for harmless subscriber fixtures, and diff for rendered docs and captured requests.
Test bundlers, linters, renderers, generators, and gateways; required headers; schema failures; raw-body signatures; retries; duplicates; redirects; DNS changes; secret rotation; versioned events; receiver downtime; and safe example data.