2026-09-23 · 6 min read · Rahul Chitturi
- openapi
- webhooks
- api
An OpenAPI callback describes an outbound request that an API may send to a URL derived from the original operation. The callback map key can contain a runtime expression referencing request or response values.
Documentation may render correctly while the deployed sender resolves a different JSON path, double-encodes the URL, or allows an untrusted callback destination to reach internal services.
Resolve one expression by hand
Record the operation, callback key, expression source, parameter location, body media type, JSON Pointer tokens, example input, resolved URL, and implementation behavior. Compare that result with generated documentation and client code.
- Distinguish runtime expressions from template syntax.
- Escape JSON Pointer tokens correctly.
- Define percent-encoding at one layer.
- Reject destinations outside the approved policy.
Treat callback URLs as outbound input
If a caller supplies any part of the destination, enforce allowed schemes, hosts, ports, DNS and IP ranges, redirects, timeouts, response limits, and network egress rules after canonical parsing. Authentication credentials must be scoped to the intended recipient.
Keep delivery retries idempotent and observable without logging secrets or complete customer payloads. A valid OpenAPI expression does not make the resolved destination safe.
Compare contract and runtime
Use Flashman's YAML/JSON converter for the OpenAPI document, URL tool for harmless resolved destinations, JSON formatter for synthetic request bodies, and diff for generated artifacts.
Test missing and null values, arrays, escaped property names, query and header sources, relative-looking values, Unicode, double encoding, redirects, DNS changes, authentication, retries, duplicate delivery, generator upgrades, and example drift.