Description
OpenAPI 3.0 callbacks document follow-up requests made by the API provider. If a local $ref beginning with #/components/callbacks/ names a missing entry, tools cannot resolve the callback definition.
Potential impact
- Documentation may omit or misrepresent asynchronous events or webhook flows.
- Reference validation errors may prevent documentation or code generation.
- API consumers may misunderstand the URL or format of a follow-up request.
Remediation
Match local callback $ref values exactly to existing names in components.callbacks. Update all references when renaming definitions; for external references, validate the URI and target document as well. Check the actual request values required by callback URL expressions.
Examples
The POST operation below references inProgress, but the first document defines only onProgress. The request body definition supplying the callback URL is omitted.
Before
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "Success"
}
},
"callbacks": {
"myEvent": {
"$ref": "#/components/callbacks/inProgress"
}
}
}
}
},
"components": {
"callbacks": {
"onProgress": {
"{$request.body#/onProgressUrl}": {
"delete": {
"responses": {
"204": {
"description": "Deleted"
}
}
}
}
}
}
}
}
After
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "Success"
}
},
"callbacks": {
"myEvent": {
"$ref": "#/components/callbacks/inProgress"
}
}
}
}
},
"components": {
"callbacks": {
"inProgress": {
"{$request.body#/inProgressUrl}": {
"delete": {
"responses": {
"204": {
"description": "Deleted"
}
}
}
}
}
}
}
}
The second document defines the referenced inProgress callback. The actual request body must supply inProgressUrl for this callback URL expression to be usable.