Webhooks & OpenAPI

Verify every webhook signature. Why OpenAPI is documentation that compiles.

Webhooks

A webhook is "HTTP callback" — instead of you polling an external service for updates, they push updates to you.

You register a URL with the service: "When a payment is made, POST to https://api.myapp.com/webhooks/stripe"

When the event happens, they POST a JSON payload to your URL.

Your webhook handler:
1. Verify the signature (HMAC-SHA256 of payload with shared secret)
2. Respond with 200 OK immediately (they'll retry on non-200)
3. Enqueue the payload for async processing (don't do heavy work in the handler)

Verification (critical!):

const signature = req.headers["x-signature"];
const computed = crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
if (signature !== `sha256=${computed}`) throw new Error("Invalid signature");

Without verification, anyone can send fake events to your webhook endpoint.

OpenAPI & API Documentation

OpenAPI (formerly Swagger) is the standard for describing REST APIs in a machine-readable format (YAML/JSON).

An OpenAPI spec describes:
• Every endpoint (path, method, parameters)
• Request body schemas
• Response schemas and status codes
• Authentication methods
• Examples

Benefits:
• Auto-generates interactive documentation (Swagger UI, Redoc)
• Auto-generates client SDKs in any language
• Enables contract testing
• The spec IS the documentation

Two approaches:
1. Design-first: write the OpenAPI spec → generate server stubs → implement
2. Code-first: annotate your code → generate spec automatically (Zod-to-OpenAPI, FastAPI, NestJS Swagger)

Always version your spec. Share it with API consumers. Use it to validate that your implementation matches the contract.