--- title: Generating OpenAPI Webhooks Definitions | daily.dev description: A walkthrough of adding a webhooks section to an OpenAPI spec, supported natively since OpenAPI 3.1 and via custom extensions since 3.0.3. Shows the raw JSON... canonical: https://daily.dev/posts/generating-openapi-webhooks-definitions-urctspfku twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: Generating OpenAPI Webhooks Definitions | daily.dev og:description: A walkthrough of adding a webhooks section to an OpenAPI spec, supported natively since OpenAPI 3.1 and via custom extensions since 3.0.3. Shows the raw JSON... og:url: https://daily.dev/posts/generating-openapi-webhooks-definitions-urctspfku og:image: https://api.daily.dev/og/posts/uRctSPFku.png og:image:alt: Generating OpenAPI Webhooks Definitions og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # Generating OpenAPI Webhooks Definitions **[Svix Blog](https://daily.dev/sources/svix)** · 5 min read · 0 upvotes · 0 comments ## Summary A walkthrough of adding a webhooks section to an OpenAPI spec, supported natively since OpenAPI 3.1 and via custom extensions since 3.0.3. Shows the raw JSON structure for a webhooks section, how FastAPI natively generates it, and a workaround for frameworks lacking built-in support by prefixing fake paths and moving them into the webhooks section post-generation. Ends noting Svix can auto-import event types from a spec's webhooks section. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### How do I add a webhooks section to my OpenAPI spec by hand? Add a top-level webhooks object structured like the paths section, keyed by event name (e.g. pet.new) instead of a URL path. Each entry defines an HTTP method (typically post) with a summary, description, operationId, and a requestBody schema describing the webhook payload, following the same shape as a normal OpenAPI path object. _Developers documenting webhook APIs can find implementation walkthroughs like this on daily.dev._ ### Which version of OpenAPI added support for webhooks? Native webhooks support was added in OpenAPI 3.1, while custom extensions such as x-webhooks could achieve the same result as far back as OpenAPI 3.0.3. Because it's a relatively recent addition, not all web frameworks generate the webhooks section automatically yet, even though FastAPI does support it natively. _Track OpenAPI ecosystem changes like this on daily.dev when deciding how to spec out webhook APIs._ ### How can I generate an OpenAPI webhooks section for a framework that doesn't support it natively? Define webhook handlers as regular routes prefixed with a marker like webhooks., then post-process the generated OpenAPI schema to strip that prefix and move those paths from the paths object into a new webhooks object. This can be done either by overriding the framework's OpenAPI generation function or via a standalone script that rewrites the exported spec JSON. _daily.dev surfaces practical workarounds like this for developers wiring up OpenAPI tooling._ ## Similar posts on daily.dev - [Webhook vs API: The Difference That Finally Clicked for Me](https://daily.dev/posts/webhook-vs-api-the-difference-that-finally-clicked-for-me-cjwanwunj) · Medium · 0 upvotes · 0 comments - [What Is a Webhook? A Simple Explanation for Beginners](https://daily.dev/posts/what-is-a-webhook-a-simple-explanation-for-beginners-5bkcihtgl) · Kilo Blog · 6 upvotes · 1 comments - [Fastify Now Speaks OpenAPI 3.2](https://daily.dev/posts/fastify-now-speaks-openapi-3-2-wgbgmoyis) · API Evangelist · 10 upvotes · 0 comments --- Tags: [#python](https://daily.dev/tags/python), [#architecture](https://daily.dev/tags/architecture), [#openapi](https://daily.dev/tags/openapi), [#fastapi](https://daily.dev/tags/fastapi) [View this post on daily.dev](https://daily.dev/posts/generating-openapi-webhooks-definitions-urctspfku) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"Generating OpenAPI Webhooks Definitions","url":"https://daily.dev/posts/generating-openapi-webhooks-definitions-urctspfku","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/generating-openapi-webhooks-definitions-urctspfku"},"datePublished":"2026-08-23T07:21:05.948Z","dateModified":"2026-08-23T07:26:41.687Z","description":"A walkthrough of adding a webhooks section to an OpenAPI spec, supported natively since OpenAPI 3.1 and via custom extensions since 3.0.3. Shows the raw JSON...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/a206cb989e6967fee4a21ed8db25f487?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/a206cb989e6967fee4a21ed8db25f487?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"Svix Blog","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"Svix Blog","logo":"https://media.daily.dev/image/upload/s--Shf9MlOr--/f_auto,q_auto/v1787469609/logos/svix?_a=BAMAMicg0","url":"https://daily.dev/sources/svix"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/generating-openapi-webhooks-definitions-urctspfku","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"python,architecture,openapi,fastapi","timeRequired":"PT5M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"Svix Blog","item":"https://daily.dev/sources/svix"},{"@type":"ListItem","position":3,"name":"Generating OpenAPI Webhooks Definitions"}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/generating-openapi-webhooks-definitions-urctspfku#faq","mainEntity":[{"@type":"Question","name":"How do I add a webhooks section to my OpenAPI spec by hand?","acceptedAnswer":{"@type":"Answer","text":"Add a top-level webhooks object structured like the paths section, keyed by event name (e.g. pet.new) instead of a URL path. Each entry defines an HTTP method (typically post) with a summary, description, operationId, and a requestBody schema describing the webhook payload, following the same shape as a normal OpenAPI path object. Developers documenting webhook APIs can find implementation walkthroughs like this on daily.dev."}},{"@type":"Question","name":"Which version of OpenAPI added support for webhooks?","acceptedAnswer":{"@type":"Answer","text":"Native webhooks support was added in OpenAPI 3.1, while custom extensions such as x-webhooks could achieve the same result as far back as OpenAPI 3.0.3. Because it's a relatively recent addition, not all web frameworks generate the webhooks section automatically yet, even though FastAPI does support it natively. Track OpenAPI ecosystem changes like this on daily.dev when deciding how to spec out webhook APIs."}},{"@type":"Question","name":"How can I generate an OpenAPI webhooks section for a framework that doesn't support it natively?","acceptedAnswer":{"@type":"Answer","text":"Define webhook handlers as regular routes prefixed with a marker like webhooks., then post-process the generated OpenAPI schema to strip that prefix and move those paths from the paths object into a new webhooks object. This can be done either by overriding the framework's OpenAPI generation function or via a standalone script that rewrites the exported spec JSON. daily.dev surfaces practical workarounds like this for developers wiring up OpenAPI tooling."}}]} ```