Declared Webhook Subscriptions So Long-Running AI Agents Can Subscribe to Events
Lets autonomous agents subscribe to events they care about instead of polling your API and burning quota.
What this signal tests
We check whether your API documents the webhooks it can deliver. The signal accepts two forms: a non-empty webhooks field in your OpenAPI 3.1 document, or a standalone AsyncAPI document published at /asyncapi.json or /.well-known/asyncapi. AsyncAPI is the event-driven sibling of OpenAPI, designed specifically to describe asynchronous and webhook-based interactions.
Why it matters for your visibility in AI
AI agents are not always one-shot. A growing share of agent work is long-running: monitor this inventory, watch for status changes, follow up when this happens. That kind of work is wasteful if the agent has to poll your API every few minutes; it is efficient if the agent can subscribe to the relevant event and be notified when something changes. Declaring webhooks gives long-running agents that subscription option. Without a webhook declaration the agent has no idea what events you publish, so it either polls aggressively (eating quota and possibly tripping your rate limits) or skips the watch step entirely. With webhooks declared, the agent subscribes once and waits - far cheaper for both sides and faster to react to real changes. This is increasingly important as autonomous agent orchestration moves from synchronous chat into long-running background work.
Pass criteria at a glance
| Criterion | Passes when |
|---|---|
| OpenAPI 'webhooks' OR AsyncAPI document published. |
How we test it
Our scanner first locates your OpenAPI document (using the openapi-discoverable signal) and checks whether it contains a non-empty webhooks object describing the events you publish. If that is absent, it probes the conventional AsyncAPI paths /asyncapi.json and /asyncapi.yaml for a valid document. Either route passes the signal; you do not need both. Both are open, parseable standards that agent frameworks already understand.
Show technical detection method
After locating openapi.json, check for non-empty 'webhooks' object; or probe /asyncapi.json|/asyncapi.yaml.
If your site fails: how to fix it
- List the webhook events your API already emits - order created, payment captured, status changed - and decide which of them are useful for external agents to subscribe to, separate from purely internal events.
- If you already publish OpenAPI, upgrade the document to OpenAPI 3.1 and declare the agent-relevant webhooks under the webhooks field; the work to do this is best done by a developer who can read the OpenAPI 3.1 specification.
- If your events are richer than OpenAPI's webhook model supports, publish a separate AsyncAPI document at /asyncapi.json describing your message channels, payload schemas, and subscription mechanics.
- Document the subscription mechanism itself - how an agent registers a callback URL, what authentication you require, and how you verify the delivery target - alongside the event schemas.
- Provide a way for subscribers to test deliveries (a sandbox event or a manual fire-test button) so agents can confirm the integration without waiting for real production events.
Quick facts
| Maturity | ESTABLISHED |
|---|---|
| Weight | low |
| Category | Agent Actions |
Primary sources
Related signals
Frequently asked questions
Do we already have webhooks but they are not documented like this?
Likely yes. Most APIs that emit webhooks document them in human-readable developer docs rather than in OpenAPI's webhooks field or an AsyncAPI document. The fix is moving that documentation into a machine-readable format alongside what you already maintain.
Does this cost anything to implement?
Both OpenAPI 3.1 webhooks and AsyncAPI are open specifications with free tooling. The cost is engineering time to translate existing webhook documentation into the structured format - typically a few days for a moderately complex API. No licensing or per-event fees apply.
How is this different from Server-Sent Events or WebSockets?
Webhooks deliver events by HTTP POST to a subscriber-provided URL - useful for long-running cross-system flows. SSE and WebSockets keep an open connection - useful for short-lived live updates. AsyncAPI can describe all three. Most agent integrations use webhooks because they survive disconnects.
Will this matter in 2026 or is it years away?
It matters now for any agent doing long-running orchestration - monitoring agents, multi-step workflows, scheduled checks. The benefit scales with the duration of the agent's task; for short synchronous chat-style use it is less important. The trend is toward longer agent runtimes, so adopt early.
Run your own scan
Run a free scan and see how your site grades across all 155 AI-readiness signals.