Introduction

Webhooks are essential for enabling real-time communication between different services and applications. They allow one system to send automated messages or information to another whenever a specific event occurs. Documenting webhooks properly is crucial for developers to understand how to integrate and utilize them effectively. In this article, we will explore three practical examples of documenting webhooks in Swagger definitions, ensuring clarity and ease of use.

Example 1: Payment Confirmation Webhook

In this scenario, a payment processing service sends a webhook notification to a merchant’s application whenever a payment is confirmed. This webhook allows the merchant to update their order status in real-time.

paths:
  /webhooks/payment-confirmation:
    post:
      summary: Payment Confirmation Webhook
      description: This webhook is triggered when a payment is successfully confirmed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orderId:
                  type: string
                  description: The unique identifier for the order.
                paymentId:
                  type: string
                  description: The unique identifier for the payment.
                amount:
                  type: number
                  description: The amount paid.
                status:
                  type: string
                  description: The status of the payment (e.g., 'confirmed').
      responses:
        '200':
          description: Successful notification processing.
        '400':
          description: Invalid request format.

Notes: Ensure that the merchant’s application can handle duplicate notifications, as webhooks might be sent multiple times.

Example 2: User Registration Webhook

This webhook is triggered whenever a new user registers on a platform. It enables external systems to take necessary actions, such as sending welcome emails or updating user databases.

paths:
  /webhooks/user-registration:
    post:
      summary: User Registration Webhook
      description: This webhook is triggered when a new user registers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  description: The unique identifier for the user.
                email:
                  type: string
                  description: The email address of the registered user.
                createdAt:
                  type: string
                  format: date-time
                  description: The timestamp when the user registered.
      responses:
        '200':
          description: Notification successfully processed.
        '400':
          description: Invalid request data.

Notes: Consider implementing a mechanism for authenticating webhook requests to ensure they come from trusted sources.

Example 3: Order Shipment Webhook

In this example, an e-commerce platform sends a webhook notification when an order has been shipped. This allows third-party logistics systems to update their records or notify customers.

paths:
  /webhooks/order-shipment:
    post:
      summary: Order Shipment Webhook
      description: This webhook is triggered when an order is shipped.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orderId:
                  type: string
                  description: The unique identifier for the order.
                trackingNumber:
                  type: string
                  description: The tracking number for the shipment.
                carrier:
                  type: string
                  description: The shipping carrier (e.g., 'UPS', 'FedEx').
                shippedAt:
                  type: string
                  format: date-time
                  description: The timestamp when the order was shipped.
      responses:
        '200':
          description: Successfully processed the shipment notification.
        '404':
          description: Order not found.

Notes: It is advisable to include a retry mechanism for failed webhook notifications to ensure reliability.