The best examples of webhook documentation in Swagger – 3 core examples and more

Real examples of the best examples of webhook documentation in Swagger

Swagger (now the OpenAPI Specification) didn’t originally ship with a perfect story for webhooks, but teams have been hacking around that for years. The most useful examples of the best examples of webhook documentation in Swagger all have a few things in common:

• They treat webhooks as first‑class operations, not footnotes.
• They clearly separate publisher (your API) and consumer (your customer’s endpoint).
• They document payloads, retries, security, and failure modes as carefully as regular REST endpoints.

The modern OpenAPI 3.1 webhooks section finally gives us a formal home for this. Let’s walk through three core examples and then a handful of additional real examples that show how to put this into practice.

Core example #1: Event notification webhooks (subscription + delivery)

The first core example of webhook documentation in Swagger is the classic event subscription and notification pattern: your API fires events when something changes (order.created, invoice.paid, user.deleted, and so on).

In well‑written specs, examples of the best examples of webhook documentation in Swagger for this pattern usually have three moving pieces:

• A subscription endpoint (your REST API)
• A webhooks section that describes the outbound calls you’ll make
• Reusable schemas for each event type

A simplified OpenAPI 3.1 snippet might look like this:

openapi: 3.1.0
info:
  title: Orders API
  version: 2025-01-01

paths:
  /webhook-subscriptions:
    post:
      summary: Create a webhook subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionRequest'
      responses:
        '201':
          description: Subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'

webhooks:
  orderCreated:
    post:
      summary: Order created event
      description: |
        Sent when a new order is created in the system.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreatedEvent'
      responses:
        '2XX':
          description: Your endpoint should return a 2xx status to acknowledge receipt.
        '410':
          description: You may return 410 Gone to indicate the webhook should be deactivated.

components:
  schemas:
    WebhookSubscriptionRequest:
      type: object
      required: [targetUrl, events]
      properties:
        targetUrl:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
            enum: [order.created, order.updated]
    OrderCreatedEvent:
      type: object
      required: [id, type, data]
      properties:
        id:
          type: string
        type:
          type: string
          enum: [order.created]
        data:
          $ref: '#/components/schemas/Order'
    Order:
      type: object
      properties:
        orderId:
          type: string
        total:
          type: number

This style mirrors what you’ll see in mature event‑driven platforms. Stripe’s webhook docs, for example, are often held up as some of the best examples (even though their public reference isn’t pure Swagger). They still follow the same principles: explicit event types, sample payloads, and clear expectations for responses and retries.

When you’re hunting for examples of the best examples of webhook documentation in Swagger for event notifications, look for:

• Named webhook channels under webhooks: (e.g., invoicePaid, subscriptionCanceled).
• Polymorphic payloads when multiple event types share a base structure.
• A short, opinionated paragraph describing when each webhook fires and what the consumer must do.

Core example #2: Synchronous callback webhooks during long‑running operations

The second core example of webhook documentation in Swagger covers long‑running operations. Think video transcoding, background exports, or AI model training. The client kicks off a job, your API responds immediately with a job ID, and later you call their webhook when the job finishes.

This is where Swagger documentation needs to describe both sides of the dance:

• The job creation endpoint.
• The status polling endpoint (optional, but common).
• The completion webhook you’ll call.

A realistic OpenAPI fragment might look like this:

paths:
  /exports:
    post:
      summary: Start a data export
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportRequest'
      responses:
        '202':
          description: Export accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJob'

  /exports/{jobId}:
    get:
      summary: Get export job status
      parameters:

        - in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Current job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJob'

webhooks:
  exportCompleted:
    post:
      summary: Export completed callback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportCompletedEvent'
      responses:
        '200':
          description: Acknowledge receipt

Examples of the best examples of webhook documentation in Swagger for this pattern usually add:

• A clear statement that no business logic should run until the completion webhook arrives.
• Expected latency ranges (seconds, minutes, hours).
• A description of idempotency: repeated callbacks for the same job ID must be safe.

This pattern is popular in 2024–2025 among AI and data‑processing APIs, where jobs can run for minutes or hours. If you browse public OpenAPI specs from ML platforms or analytics vendors, you’ll see more real examples adopting the webhooks section instead of bolting callbacks into paths as fake inbound endpoints.

Core example #3: Third‑party integration webhooks (GitHub‑style events)

The third core example of webhook documentation in Swagger is the integration platform model: you expose dozens of event types so customers can wire your product into their own workflows. Think GitHub, Slack, or project management tools.

In these situations, the best examples of webhook documentation in Swagger:

• Group events by domain (issues, pull requests, deployments).
• Provide a single subscription mechanism but many payload schemas.
• Offer sample payloads that match real production traffic as closely as possible.

A spec might define a generic integrationEvent webhook, then use oneOf to describe the real examples of events:

webhooks:
  integrationEvent:
    post:
      summary: Generic integration event
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:

                - $ref: '#/components/schemas/IssueOpenedEvent'
                - $ref: '#/components/schemas/IssueClosedEvent'
                - $ref: '#/components/schemas/PullRequestMergedEvent'
              discriminator:
                propertyName: eventType
      responses:
        '2XX':
          description: Acknowledge receipt of any integration event

Examples of the best examples of webhook documentation in Swagger for integration platforms often pair this with narrative docs that show how to:

• Register a webhook.
• Filter which event types you want.
• Verify signatures.

If you’re looking for inspiration, public API references from developer‑focused tools are a good hunting ground. Even when they don’t publish pure Swagger, the same structure can be mirrored in your OpenAPI file.

More real examples: retries, signatures, and versioning in Swagger

The three core examples above cover the shape of webhook calls. The next tier of examples of the best examples of webhook documentation in Swagger focus on behavior: retries, security, and evolution over time.

Retry policies and failure handling

In 2025, almost every serious webhook provider documents retry behavior. Your Swagger file can do more than list response codes; it can describe how your system behaves when things go wrong.

Good real examples include:

• A short description on each webhook operation explaining how many retries you’ll attempt and backoff strategy (fixed, exponential, etc.).
• Clarifying which status codes trigger retries (e.g., 5xx and timeouts) and which do not (4xx).
• Using default responses to document unexpected errors.

For instance:

webhooks:
  paymentFailed:
    post:
      summary: Payment failed event
      description: |
        We retry delivery up to 10 times over 24 hours for 5xx responses or timeouts.
        4xx responses are treated as permanent failures.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentFailedEvent'
      responses:
        '2XX':
          description: Acknowledge receipt
        '4XX':
          description: Permanent failure. No further retries will be attempted.
        '5XX':
          description: Temporary failure. We will retry with exponential backoff.

This is a simple tweak, but if you compare it to weaker specs, you’ll see why it belongs in any list of the best examples of webhook documentation in Swagger.

Security: HMAC signatures and shared secrets

Security is where a lot of otherwise solid specs fall down. In 2024–2025, HMAC signatures are the default expectation. Your Swagger documentation should explain how to verify that a webhook really came from you.

Patterns you’ll see in real examples include:

• Defining a securitySchemes entry for a custom header.
• Documenting the signature algorithm (e.g., SHA‑256) and the string to sign.
• Linking to external resources on secure cryptography practices. For a grounding in general security concepts, the National Institute of Standards and Technology (NIST) at nist.gov offers detailed guidance on hashing and key management.

Example:

components:
  securitySchemes:
    webhookSignature:
      type: apiKey
      in: header
      name: X-Signature

webhooks:
  userUpdated:
    post:
      summary: User updated event
      security:

        - webhookSignature: []
      description: |
        We sign each request using HMAC-SHA256 with your webhook secret.
        The raw request body is used as the message.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdatedEvent'

The best examples of webhook documentation in Swagger always explain how to recompute and compare this signature in the consumer’s code, even if that detailed code sample lives in a separate developer guide.

Versioning and schema evolution

Webhooks age. Fields get added, deprecated, or removed. If your documentation doesn’t prepare integrators for this, you end up with brittle integrations.

Examples of the best examples of webhook documentation in Swagger for versioning tend to:

• Include a version field in each payload schema.
• Use OpenAPI’s deprecated: true flag on fields.
• Document a sunset policy for breaking changes and link to a public change log.

While versioning strategies can vary, the underlying principle of backward compatibility is widely discussed in software engineering education. For developers who want to go deeper into API design principles more broadly, resources from institutions like Harvard University’s computer science courses can provide useful context for thinking about long‑term interface design.

How teams actually use Swagger for webhooks in 2024–2025

In 2024–2025, three trends show up repeatedly when you look at real examples of the best examples of webhook documentation in Swagger:

• OpenAPI 3.1 adoption is finally picking up, which means the webhooks section is no longer exotic.
• Single‑source‑of‑truth approaches are winning. Teams generate both interactive docs and SDKs from one OpenAPI file, including webhook models.
• Contract testing is expanding to webhooks. The same schemas you see in Swagger are used in automated tests to validate that outbound webhook payloads match the contract.

This is not just theory. Developer‑heavy organizations now routinely treat their OpenAPI files as part of their change‑management process. Schema updates for webhooks go through code review, are tested, and are surfaced in change logs before rollout.

For teams in regulated industries—healthcare, finance, government—this style of strict contract documentation aligns with broader expectations around data handling and reliability. While not webhook‑specific, agencies like the U.S. Department of Health & Human Services at hhs.gov and the Centers for Disease Control and Prevention at cdc.gov publish detailed data standards and interoperability guidelines that push vendors toward clearer, machine‑readable contracts.

Putting it together: patterns to copy from the best examples

If you’re trying to create your own examples of the best examples of webhook documentation in Swagger – 3 core examples and more, here’s the pattern that consistently shows up in strong real‑world specs:

• Use OpenAPI 3.1 and the dedicated webhooks section.
• Mirror your business concepts in the names of your webhooks, not generic labels.
• Treat webhooks as first‑class operations with:
  • Clear summary and description.
  • Fully typed requestBody schemas.
  • Realistic sample payloads.
  • Documented retry and error behavior.
• Define security schemes for signatures and explain verification.
• Plan for evolution: version fields, deprecated properties, and a public change log.

When you compare your spec against these examples of the best examples of webhook documentation in Swagger, you’ll know you’re on the right track if a new integrator can answer, from the docs alone:

• When will this webhook fire?
• What does the payload look like, field by field?
• How do I know the call really came from you?
• What happens if my endpoint is down, slow, or returns errors?
• How will this payload change next year?

If your Swagger file answers all of that, you’re no longer guessing—you’re operating at the same level as the strongest real examples in the ecosystem.

FAQ: examples, patterns, and practical questions

What are good examples of webhook documentation in Swagger I can copy from?

Look for public OpenAPI 3.0 or 3.1 specs from developer‑first companies that expose event‑driven APIs. Even when they don’t use the webhooks section yet, their patterns for schemas, security, and error handling are usually strong. Then translate those patterns into the modern webhooks block.

Can you give an example of modeling retries in Swagger for webhooks?

Yes. The cleanest approach is to describe retry behavior in the description of the webhook operation and map status codes to retry vs. no‑retry behavior. For instance, you can state that 5xx responses trigger exponential backoff retries for up to 24 hours, while 4xx responses are treated as permanent failures. You don’t need a custom extension for this; plain text plus clear response sections are enough.

Do I have to use the webhooks section, or can I just use normal paths?

You can model webhooks using regular paths as if your consumer’s endpoint lived inside your API, but it’s confusing. The webhooks section was added to OpenAPI specifically to represent outbound calls your service makes. If you want your documentation to match modern best examples of webhook documentation in Swagger, use webhooks.

How many different webhook events should I expose in my Swagger file?

Expose every event that integrators can subscribe to, but avoid inventing dozens of nearly identical events. The better real examples group related changes into a single event type with a clear schema. Use enums or discriminators to distinguish subtypes instead of fragmenting your model into a long list of one‑off events.

How detailed should my webhook payload schemas be?

As detailed as your regular REST responses. The strongest examples of webhook documentation in Swagger define types, formats, enums, and nullable fields. They also include realistic examples so consumers can copy and paste payloads into tests. Underspecified schemas are a common source of production bugs.