PetstoreAPI Webhooks Protocol Guide

Modern Petstore API provides webhook support for event-driven HTTP callbacks where our server pushes real-time notifications to your endpoints. Our webhook system delivers events for pet adoptions, order status changes, payment confirmations, and pet availability updates directly to your registered URL with HMAC signature verification for security.

Overview

Protocol: HTTPS POST callbacks

Pattern: Event-driven (Server → Client)

Direction: Unidirectional (Server calls your endpoint)

When to Use Webhooks:

✅ Real-time event notifications

✅ Order status updates

✅ Payment confirmations

✅ Pet adoption notifications

✅ Inventory alerts

When NOT to Use Webhooks:

❌ You need to request data (use REST instead)

❌ Your endpoint is not publicly accessible (use polling instead)

How Webhooks Work

Event Occurs                    Your Server
    │                              │
    ▼                              │
Petstore API                      │
    │                              │
    ├────── HTTP POST ────────────>│
    │      (webhook payload)       │
    │                              │
    │                       ┌──────┴──────┐
    │                       │ Process     │
    │                       │ Event       │
    │                       └──────┬──────┘
    │                              │
    │<───── HTTP 200 OK ───────────┤
    │      (acknowledgment)         │

Key Characteristics:

Server initiates the request

Push-based (no polling needed)

Event-driven architecture

HMAC signature verification

Automatic retry on failure

Webhook Events

Pet Events

Pet Adopted

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "eventType": "pet.adopted",
  "timestamp": "2025-01-06T12:00:00Z",
  "data": {
    "pet": {
      "id": "pet_fYrZzCW9E1WIOyGw",
      "name": "Buddy",
      "species": "DOG",
      "status": "ADOPTED"
    },
    "adopter": {
      "id": "019b4137-6d8e-5c2b-e9f4-a3b5c8d7e2f1",
      "name": "John Doe",
      "email": "john@example.com"
    },
    "adoptionDate": "2025-01-06"
  }
}

Pet Status Changed

{
  "id": "019b4127-54d5-76d9-b626-0d4c7bfce5b6",
  "eventType": "pet.status_changed",
  "timestamp": "2025-01-06T12:00:00Z",
  "data": {
    "petId": "pet_fYrZzCW9E1WIOyGw",
    "oldStatus": "AVAILABLE",
    "newStatus": "PENDING",
    "reason": "Adoption application received"
  }
}

Order Events

Order Created

{
  "id": "019b4135-89c2-724a-a825-c1d8a0e9f4c3",
  "eventType": "order.created",
  "timestamp": "2025-01-06T12:00:00Z",
  "data": {
    "order": {
      "id": "019b4141-e5f3-a1b7-c4d8-9f6e2a5b8c1d",
      "status": "PENDING",
      "items": [
        {
          "productId": "019b4145-a6c2-b8d3-e7f4-5a9b1c2d3e4f",
          "quantity": 2,
          "price": 29.99
        }
      ],
      "total": 59.98,
      "currency": "USD"
    },
    "customer": {
      "id": "019b4137-6d8e-5c2b-e9f4-a3b5c8d7e2f1",
      "email": "customer@example.com"
    }
  }
}

Order Status Changed

{
  "id": "019b4138-3d5f-8b1c-d9e7-f0a2b4c8e6d1",
  "eventType": "order.status_changed",
  "timestamp": "2025-01-06T12:00:00Z",
  "data": {
    "orderId": "order_abc123",
    "oldStatus": "PENDING",
    "newStatus": "PROCESSING",
    "timestamp": "2025-01-06T12:00:00Z"
  }
}

Payment Events

Payment Succeeded

{
  "id": "019b4139-a7e4-6c3f-b2a1-e9f8d5c7b4a9",
  "eventType": "payment.succeeded",
  "timestamp": "2025-01-06T12:00:00Z",
  "data": {
    "payment": {
      "id": "019b4142-c4d6-f8a9-b2e3-7d1c5f9a8e4b",
      "orderId": "order_abc123",
      "amount": 150.00,
      "currency": "USD",
      "status": "SUCCEEDED"
    },
    "paymentMethod": {
      "type": "CARD",
      "last4": "4242",
      "brand": "Visa"
    }
  }
}

Payment Failed

{
  "id": "019b4140-b2c8-9d4e-a3f6-c8e7b5d9a2f1",
  "eventType": "payment.failed",
  "timestamp": "2025-01-06T12:00:00Z",
  "data": {
    "payment": {
      "id": "019b4143-d8e4-a7f2-c5b9-6e4a8d3c7f1b",
      "orderId": "order_def456",
      "amount": 75.00,
      "currency": "USD",
      "status": "FAILED"
    },
    "error": {
      "code": "INSUFFICIENT_FUNDS",
      "message": "The card has insufficient funds."
    }
  }
}

Setting Up Webhooks

1. Register Your Webhook URL

Response:

{
  "id": "019b4144-f1b7-e5c8-d4a6-3c7f9b2e8d5a",
  "url": "https://your-app.com/webhooks/petstore",
  "events": ["pet.adopted", "pet.status_changed", "..."],
  "secret": "whsec_xxx...",
  "status": "active",
  "createdAt": "2025-01-06T12:00:00Z"
}

2. Create Webhook Endpoint

3. Test Your Webhook

Signature Verification

Why Verify Signatures?

✅ Ensure webhook is from Petstore API

✅ Detect tampering

✅ Prevent fraud

Verification Process

Best Practices

1. Always Return 200 OK Quickly

2. Handle Duplicate Events

3. Retry Logic

The API will retry webhooks that fail:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	1 hour

After 5 failed attempts, the webhook is disabled.

4. Idempotency

Make your webhook handlers idempotent:

Security

1. Use HTTPS

Always use HTTPS for your webhook endpoint.

2. Verify Signatures

Never process webhook events without signature verification.

3. Validate Payloads

4. Rate Limiting

Managing Webhooks

List Webhooks

Get Webhook Details

Update Webhook

Delete Webhook

Troubleshooting

Not Receiving Webhooks

Check webhook status is active

Verify endpoint URL is publicly accessible

Confirm HTTPS certificate is valid

Check server logs for connection attempts

Test with webhook test endpoint

Signature Verification Fails

Ensure you're using the correct secret

Verify you're comparing the entire signature

Check for encoding issues

High Failure Rate

Ensure endpoint responds quickly (< 5 seconds)

Always return 200 OK (even if processing fails later)

Implement retry logic in your application

Monitor endpoint uptime

Comparison with Alternatives

Feature	Webhooks	Polling	WebSocket
Latency	Very Low	High	Very Low
Server Load	Low	High	Medium
Complexity	Low	Low	High
Public Endpoint	Required	Not Required	Required
Real-time	✅	❌	✅

Interactive Documentation

API Specification: OpenAPI 3.2

Webhooks in OpenAPI: See webhooks section

Protocol Overview: All Protocols

AsyncAPI Specification

REST API Guide - For request/response patterns

Quick Start Guide

Overview#

How Webhooks Work#

Webhook Events#

Pet Events#

Pet Adopted#

Pet Status Changed#

Order Events#

Order Created#

Order Status Changed#

Payment Events#

Payment Succeeded#

Payment Failed#

Setting Up Webhooks#

1. Register Your Webhook URL#

2. Create Webhook Endpoint#

3. Test Your Webhook#

Signature Verification#

Why Verify Signatures?#

Verification Process#

Best Practices#

1. Always Return 200 OK Quickly#

2. Handle Duplicate Events#

3. Retry Logic#

4. Idempotency#

Security#

1. Use HTTPS#

2. Verify Signatures#

3. Validate Payloads#

4. Rate Limiting#

Managing Webhooks#

List Webhooks#

Get Webhook Details#

Update Webhook#

Delete Webhook#

Troubleshooting#

Not Receiving Webhooks#

Signature Verification Fails#

High Failure Rate#

Comparison with Alternatives#

Interactive Documentation#

Related Resources#