You’ve learned how webhooks work, how they differ from REST APIs, and how to document them effectively. Now, it’s time to put your skills to the test!

What to expect in these exercises?

Just like with REST API documentation, webhook documentation has different levels of complexity. These exercises will help you:

  • Understand real-world webhook use cases (Payments, E-commerce, and Notifications).
  • Write structured documentation covering webhook payloads, security, and error handling.
  • Tackle increasing levels of difficulty from beginner to expert.

How it works?

The chapter contains 5 hands-on exercises that simulate real-world API documentation tasks.

These exercises introduce you to basic webhook documentation. You’ll start with single events, learn how to structure webhook docs, and gradually move towards handling more complex scenarios.

Exercise 1: Documenting a Basic Webhook (API-based Registration)

Scenario: You are assigned to document a **new webhook for an e-commerce platform** that notifies users when an order is successfully placed.

Your Task: Write a structured API reference document covering:

  • Overview of the webhook.
  • How developers register a webhook URL using an API.
  • Webhook trigger event details.
  • Request format and expected response.
  • Security best practices.
  • Webhook retry policy.
  • How developers can test this webhook.

Webhook Registration

Developers register their webhook using the following API endpoint:

        POST /webhooks/register
        {
            "event": "order.placed",
            "url": "https://yourwebhookurl.com/order"
        }

Webhook Event Details

Event Name: order.placed

Triggered When: A customer successfully places an order.

HTTP Method: POST

Webhook Destination: User-provided webhook URL

Example Webhook Payload
        {
            "event": "order.placed",
            "data": {
                "order_id": "ORD12345",
                "customer": {
                    "name": "Alice Johnson",
                    "email": "alice@example.com"
                },
                "total_amount": 99.99,
                "currency": "USD"
            }
        }

Solution to Exercise 1

1. Overview

The **Order Placed Webhook** notifies subscribed systems whenever a customer places an order. This webhook helps external services update inventory, trigger shipping processes, and notify users in real-time.

2. Webhook Registration (API-based)

Developers must register their webhook URL using the following request:

        curl -X POST "https://api.webhookexample.com/webhook/register" \
        -H "Authorization: Bearer your_token" \
        -H "Content-Type: application/json" \
        -d '{"callback_url": "https://client.com/webhook-receiver"}'

3. Webhook Event

Event Name Trigger Condition Description
order.placed When a customer completes an order Fires when an order is successfully placed on the platform.

4. Expected Response from Client

The client must return a **200 OK** status to confirm successful processing of the webhook.

5. Webhook Security - Verifying Webhooks

Each webhook request includes an **X-Signature** header for verification.

Clients must compute an **HMAC-SHA256 hash** of the payload using their secret key and compare it with the signature.

6. Webhook Retry Policy

If the webhook fails (does not return **200 OK**), the system **retries up to 3 times** with exponential backoff.

7. Testing Webhooks

Developers can use **Postman** or **cURL** to test webhook requests:

        curl -X POST "https://yourwebhookurl.com/order" -H "Content-Type: application/json" -d '{
            "event": "order.placed",
            "data": {
                "order_id": "ORD12345",
                "customer": {"name": "Alice Johnson", "email": "alice@example.com"},
                "total_amount": 99.99,
                "currency": "USD"
            }
        }'


Exercise 2: Documenting Multiple Webhook Events (API-based Registration)

Scenario: You are documenting webhooks for an **order tracking system** that sends updates when an order's status changes.

Your Task: Document the following webhook events:

  • order.placed – Triggered when an order is successfully placed.
  • order.shipped – Fired when an order is shipped.
  • order.delivered – Sent when the order is successfully delivered.

Webhook Registration

Developers register their webhook using the following API endpoint:

        POST /webhooks/register
        {
            "events": ["order.placed", "order.shipped", "order.delivered"],
            "url": "https://yourwebhookurl.com/order-tracking"
        }

Webhook Event Details

Endpoint: POST /webhooks/order-tracking

Destination: User-provided webhook URL

Example Webhook Payload
        {
            "event": "order.shipped",
            "data": {
                "order_id": "ORD67890",
                "customer": {
                    "name": "John Doe",
                    "email": "john@example.com"
                },
                "status": "shipped",
                "tracking_number": "TRACK12345",
                "expected_delivery": "2024-03-05T12:00:00Z"
            }
        }

Solution to Exercise 2

1. Overview

The **Order Tracking Webhooks** notify subscribed systems when an order moves through various stages: placed, shipped, and delivered.

2. Webhook Registration

Developers must register their webhook URL using the following request:

        curl -X POST "https://api.webhookexample.com/webhook/register" \
        -H "Authorization: Bearer your_token" \
        -H "Content-Type: application/json" \
        -d '{"events": ["order.placed", "order.shipped", "order.delivered"], "callback_url": "https://client.com/webhook-receiver"}'

3. Webhook Events

Event Name Trigger Condition Description
order.placed When an order is placed Triggers when a customer successfully places an order.
order.shipped When an order is shipped Fires when an order is shipped from the warehouse.
order.delivered When an order is delivered Notifies when an order reaches the customer.

4. Expected Response from Client

The client must return a **200 OK** status to confirm successful processing of the webhook.

5. Webhook Security - Verifying Webhooks

Each webhook request includes an **X-Signature** header for verification.

Clients must compute an **HMAC-SHA256 hash** of the payload using their secret key and compare it with the received signature.

6. Webhook Retry Policy

If the webhook fails (does not return **200 OK**), the system **retries up to 3 times** with an increasing delay.

7. Testing Webhooks

Developers can use **Postman** or **cURL** to test webhook responses:

        curl -X POST "https://yourwebhookurl.com/order-tracking" -H "Content-Type: application/json" -d '{
            "event": "order.shipped",
            "data": {
                "order_id": "ORD67890",
                "customer": {"name": "John Doe", "email": "john@example.com"},
                "status": "shipped",
                "tracking_number": "TRACK12345",
                "expected_delivery": "2024-03-05T12:00:00Z"
            }
        }'


Exercise 4: Configuring a Webhook via UI-Based Registration

Scenario: You are documenting a **webhook for a subscription-based SaaS platform**. The platform allows customers to receive notifications when a user **subscribes**, **updates their plan**, or **cancels their subscription**.

Key Difference: Unlike API-based registration, developers must manually **configure their webhook URL in the platform’s dashboard.**

Your Task: Document the following:

  • How users register the webhook in the platform UI.
  • Webhook event triggers.
  • Webhook request format.
  • Expected response from the client.
  • Security considerations.

Webhook Registration (UI-Based)

Users must configure their webhook by following these steps:

  1. Log in to the **SaaS platform dashboard**.
  2. Navigate to **Settings > Webhooks**.
  3. Enter your webhook URL in the **Webhook URL** field.
  4. Select the events you want to subscribe to:
    • subscription.created – When a new subscription is created.
    • subscription.updated – When a user updates their subscription plan.
    • subscription.canceled – When a subscription is canceled.
  5. Click **Save** to activate the webhook.

Example Webhook Payload

        {
            "event": "subscription.updated",
            "data": {
                "user_id": "USR45678",
                "plan": "Premium",
                "status": "active",
                "updated_at": "2024-03-12T08:30:00Z"
            }
        }

Solution to Exercise 4

1. Overview

The **Subscription Webhook** notifies external systems when users subscribe, update, or cancel their plan.

2. Webhook Registration (UI-Based)

Unlike API-based registration, users must **manually enter their webhook URL** in the platform’s dashboard.

3. Webhook Events

Event Name Trigger Condition Description
subscription.created When a new user subscribes Notifies the client when a user signs up for a subscription.
subscription.updated When a user changes their plan Fires when a user upgrades or downgrades their plan.
subscription.canceled When a user cancels Triggers when a subscription is terminated.

4. Expected Response from Client

The client must return a **200 OK** status to confirm webhook processing.

5. Webhook Security Considerations

  • **Use HTTPS** to prevent data interception.
  • **Verify the request origin** by checking the **X-SaaS-Signature** header.
  • **Log all webhook requests for debugging.**

6. Webhook Testing

Users can trigger test events via the **SaaS dashboard**:

  1. Go to **Settings > Webhooks > Test Webhook**.
  2. Select an event (e.g., **subscription.updated**).
  3. Click **Send Test** to see the webhook response.

7. Sample Webhook Response

        {
            "status": "success",
            "message": "Webhook received and processed successfully."
        }


Exercise 3: Securing Webhooks with Authentication (API-based Registration)

Scenario: You are documenting a webhook for a **payment gateway** that sends real-time transaction updates. Webhooks must be secured using authentication to prevent unauthorized access.

Your Task: Document the following:

  • Overview of the webhook.
  • How developers register their webhook using an API.
  • Webhook authentication (API keys, secret tokens).
  • Expected webhook request and response format.
  • Webhook retry policy.
  • Best practices for logging and debugging.

Webhook Registration

Developers must register their webhook using an API key:

        POST /webhooks/register
        {
            "events": ["payment.success", "payment.failed"],
            "url": "https://yourwebhookurl.com/payment",
            "api_key": "your_api_key"
        }

Webhook Event Details

Endpoint: POST /webhooks/payment

Destination: User-provided webhook URL

Example Webhook Payload
        {
            "event": "payment.success",
            "data": {
                "transaction_id": "TXN12345",
                "amount": 150.00,
                "currency": "USD",
                "status": "success",
                "timestamp": "2024-03-10T10:00:00Z"
            },
            "signature": "abcd1234efgh5678"
        }

Solution to Exercise 3

1. Overview

The **Payment Webhook** notifies merchants when a transaction succeeds or fails. This webhook helps update transaction records, trigger email notifications, and sync payment statuses.

2. Webhook Registration

Developers must register their webhook URL using the following request:

        curl -X POST "https://api.paymentgateway.com/webhook/register" \
        -H "Authorization: Bearer your_api_key" \
        -H "Content-Type: application/json" \
        -d '{"events": ["payment.success", "payment.failed"], "callback_url": "https://client.com/webhook-receiver"}'

3. Webhook Events

Event Name Trigger Condition Description
payment.success When a payment is successfully processed Notifies the client about successful payments.
payment.failed When a payment fails Alerts the client about failed transactions.

4. Webhook Authentication

Each webhook request includes a **signature** in the payload. Clients must verify this using their secret key.

        import hmac
        import hashlib

        secret = "your-secret-key"
        payload = '{"event":"payment.success","data":{"transaction_id":"TXN12345"}}'
        received_signature = "abcd1234efgh5678"

        calculated_signature = hmac.new(
            key=secret.encode(),
            msg=payload.encode(),
            digestmod=hashlib.sha256
        ).hexdigest()

        if calculated_signature == received_signature:
            print("Webhook verified!")
        else:
            print("Invalid webhook request.")

5. Webhook Retry Policy

If the webhook fails (does not return **200 OK**), the system retries **up to 3 times**.

6. Best Practices for Logging and Debugging

  • **Log all webhook requests and responses.**
  • **Validate signatures before processing.**
  • **Respond quickly with HTTP 200 OK.**
  • **Monitor logs for failed webhook deliveries.**

7. Testing Webhooks

Developers can use **Postman** or **cURL** to test webhook requests:

        curl -X POST "https://yourwebhookurl.com/payment" -H "Content-Type: application/json" -d '{
            "event": "payment.success",
            "data": {
                "transaction_id": "TXN12345",
                "amount": 150.00,
                "currency": "USD",
                "status": "success",
                "timestamp": "2024-03-10T10:00:00Z"
            },
            "signature": "abcd1234efgh5678"
        }'


Exercise 5: Setting Up a Webhook for a Collaboration Platform (UI-based Registration)

Scenario: You are documenting how users can **set up a webhook in Slack** to receive real-time notifications when messages are posted in a specific channel.

Key Difference: Unlike API-based registration, webhooks must be manually **configured in the Slack Webhooks dashboard.**

Your Task: Document the following:

  • How users register the webhook in the Slack UI.
  • Webhook event triggers.
  • Webhook request format.
  • Expected response from the client.
  • Best practices for handling webhook security.

Webhook Registration (UI-Based)

Users must configure their webhook URL in **Slack’s Webhooks UI**:

  1. Log in to the **Slack App Directory**.
  2. Navigate to **Manage Apps > Incoming Webhooks**.
  3. Click **Add New Webhook to Workspace**.
  4. Select the channel where notifications should be sent.
  5. Copy the generated **Webhook URL** (e.g., https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX).
  6. Save your settings to activate the webhook.

Example Webhook Payload

        {
            "text": "A new message was posted in #general",
            "channel": "#general",
            "username": "BotUser",
            "timestamp": "2024-03-15T12:00:00Z"
        }

Solution to Exercise 5

1. Overview

The **Slack Webhook** allows external applications to send real-time notifications to a Slack channel when an event occurs.

2. Webhook Registration (UI-Based)

Users must manually set up the webhook through the **Slack Webhooks dashboard** instead of using an API request.

3. Webhook Events

Event Name Trigger Condition Description
message.posted When a message is posted Triggers when a user sends a new message in the specified Slack channel.

4. Expected Response from Client

The client must return a **200 OK** status to confirm successful webhook processing.

5. Webhook Security Considerations

  • **Use HTTPS** to prevent data interception.
  • **Verify requests** by checking Slack’s **X-Slack-Signature** header.
  • **Restrict webhook access** to trusted applications only.

6. Webhook Testing

Users can trigger test events in the **Slack Webhooks UI**:

  1. Go to **Manage Apps > Incoming Webhooks**.
  2. Click **Test Webhook**.
  3. Check if the message appears in the Slack channel.

7. Sample Webhook Response

        {
            "status": "success",
            "message": "Webhook received and posted to Slack."
        }


Exercise 6: Setting Up a Webhook in GitHub (UI-based Registration)

Scenario: You are documenting how users can **set up a webhook in GitHub** to receive real-time notifications when a repository is updated.

Key Difference: Unlike API-based registration, webhooks must be manually **configured in the GitHub Webhooks settings.**

Your Task: Document the following:

  • How users register the webhook in the GitHub UI.
  • Webhook event triggers.
  • Webhook request format.
  • Expected response from the client.
  • Security best practices for handling webhook requests.

Webhook Registration (UI-Based)

Users must configure their webhook URL in **GitHub’s Webhooks UI**:

  1. Log in to **GitHub** and go to your repository.
  2. Navigate to **Settings > Webhooks**.
  3. Click **Add webhook**.
  4. In the **Payload URL** field, enter your webhook endpoint (e.g., https://yourwebhookurl.com/github).
  5. Select the **Content Type** as application/json.
  6. Choose the events to subscribe to (e.g., **Push Events** and **Pull Requests**).
  7. Click **Add webhook** to activate it.

Example Webhook Payload

        {
            "event": "push",
            "repository": {
                "name": "my-repo",
                "owner": "user123"
            },
            "commits": [
                {
                    "id": "abc123",
                    "message": "Updated README",
                    "timestamp": "2024-03-15T10:30:00Z"
                }
            ]
        }

Solution to Exercise 6

1. Overview

The **GitHub Webhook** allows external applications to receive notifications when specific actions occur in a repository, such as a push event or a pull request.

2. Webhook Registration (UI-Based)

Unlike API-based registration, users must **manually configure** the webhook in **GitHub’s repository settings**.

3. Webhook Events

Event Name Trigger Condition Description
push When new code is pushed Triggers when commits are pushed to the repository.
pull_request When a pull request is opened or closed Fires when a developer opens or merges a pull request.

4. Expected Response from Client

The client must return a **200 OK** status to confirm webhook processing.

5. Webhook Security Considerations

  • **Use HTTPS** to secure webhook payloads.
  • **Verify GitHub’s secret token** to ensure authenticity.
  • **Restrict webhook access** to trusted applications.

6. Webhook Testing

Users can test webhooks in **GitHub’s Webhooks UI**:

  1. Go to **Settings > Webhooks**.
  2. Click **Recent Deliveries**.
  3. Verify the webhook payload and response.

7. Sample Webhook Response

        {
            "status": "success",
            "message": "Webhook received and processed successfully."
        }
Previous Continue

Found value in the course? Your support fuels my work!
Buy Me A Coffee
Course completed
85%

Have an issue? Please provide specific feedback by reporting an issue.