Practise the vocabulary of OpenAPI 3.1 webhooks — the top-level webhooks object, path item definitions for outbound calls, subscription patterns, and how webhooks differ from the older callbacks feature.
0 / 5 completed
1 / 5
Where are webhooks defined in an OpenAPI 3.1 document?
OpenAPI 3.1 introduced a top-level webhooks object (alongside paths) for documenting outbound callbacks that your API sends. Each key is a webhook name and the value is a Path Item Object describing the HTTP request your API will make to the subscriber's endpoint.
2 / 5
What is a webhook path item in OpenAPI 3.1?
A webhook path item in the webhooks map is a standard Path Item Object describing the outbound HTTP call. It typically defines a post operation with a request body schema (the event payload) and expected response codes, giving consumers enough information to implement and validate their listener endpoint.
3 / 5
What is the typical subscription model for webhooks described in an OpenAPI document?
OpenAPI documents the webhook payload shape and delivery semantics, not the subscription mechanism itself. Subscribers typically register via a dedicated REST endpoint (in paths). Once registered, the API server pushes event payloads to the subscriber's URL using the HTTP request structure described in the webhooks object.
4 / 5
What is the difference between OpenAPI 3.1 webhooks and callbacks?
Callbacks (introduced in OpenAPI 3.0) are tied to a specific API operation — a callback URL provided in a request triggers a later call. Webhooks (OpenAPI 3.1) are first-class, operation-independent events. They represent any outbound call the server makes autonomously, such as billing events, status updates, or CI job completions.
5 / 5
How should a webhook subscriber respond to signal successful receipt according to common OpenAPI webhook documentation conventions?
Webhook delivery conventions documented in OpenAPI expect the subscriber to return a 2xx response quickly to acknowledge receipt. The API server typically retries on non-2xx or timeout responses. Returning 200 OK or 204 No Content is the standard pattern; processing should happen asynchronously after acknowledgement to avoid timeouts.