Why doesn't OpenAPI natively describe webhooks before version 3.1?

Prior to OpenAPI 3.1, the specification's paths object was designed entirely around describing endpoints the API provider exposes for consumers to call — there was no structural equivalent for describing calls that flow in the opposite direction, where the API provider calls out to a URL the consumer controls, as webhooks do.

Teams needing to document webhooks before 3.1 typically worked around this limitation by describing webhook payloads as regular schemas under components and explaining the actual delivery mechanism in prose within the description fields, since there was no first-class structural way to say "here's an operation the consumer's server must implement to receive this."

OpenAPI 3.1 introduced a dedicated top-level webhooks object, structured almost identically to paths, specifically to close this gap — each entry describes an operation the API provider will call on the consumer's registered endpoint, complete with its own request body schema and expected response, giving webhooks the same first-class, machine-readable documentation treatment that regular endpoints have always had.