2026-09-23 · 8 min read
- openapi
- webhooks
- api
OpenAPI callbacks describe requests that an API provider may send as a consequence of an operation. A callback map key can use a runtime expression to derive the target URL from the original request or response.
This makes asynchronous contracts discoverable, but it joins specification syntax, JSON Pointer resolution, URL construction, authentication, retries, and outbound network security in one feature.
Choose an expression source deliberately
Decide whether the destination comes from a query value, header, path parameter, request body, or response value. Specify the media type and data shape so a runtime body expression resolves against a predictable structured document.
- Use exact runtime-expression syntax.
- Escape ~ and / inside JSON Pointer tokens.
- Define missing, null, and non-string behavior.
- Provide harmless complete examples.
Construct and validate the destination once
Define where percent-encoding occurs and avoid concatenating already encoded fragments through several layers. Parse the final URL canonically, allow only intended schemes, hosts and ports, and apply redirect, DNS, IP-range, timeout, and response-size controls.
Re-evaluate destination policy at delivery time so DNS changes and redirects cannot bypass outbound restrictions. Never attach a shared credential to an arbitrary caller-supplied host.
Specify a reliable delivery protocol
Document callback method, headers, media type, signature or authentication profile, event identifier, ordering, timeout, retry schedule, duplicate handling, and terminal failure policy. Receivers should process an event idempotently.
Keep observability privacy-safe: record event and attempt identifiers, destination category, timing, status, and failure class without storing authorization headers or full sensitive payloads.
Verify the rendered and running contract
Use Flashman's YAML/JSON converter for the OpenAPI source, URL tool for harmless resolved targets, JSON formatter for synthetic bodies, diff for generated documentation and clients, and hash tool for public fixture identity.
Test every expression source, escaped names, arrays, missing and null values, Unicode, percent encoding, redirects, DNS changes, authentication, signature verification, timeout, retry, duplicate delivery, receiver downtime, generator upgrades, and drift between examples and runtime.