hatch-surf/examples/webhook-integration.md

Webhook Integration Examples

Real-world examples of using Hatch for webhook capture, testing, and debugging.

Example 1: Stripe Webhook Testing

Capture and test Stripe webhook events in development.

Setup

# Start Hatch server
hatch serve &

# Capture Stripe webhook events
hatch capture /webhooks/stripe \
  -method POST \
  -header 'Stripe-Signature:whsec_test123' \
  -body '{"id":"evt_123","type":"payment_intent.succeeded","data":{"object":{"id":"pi_456","amount":2000,"currency":"usd"}}}'

Development Workflow

# 1. Capture incoming webhook
hatch capture /webhooks/stripe -body '{"type":"checkout.session.completed","data":{"object":{"id":"cs_789"}}}'

# 2. Inspect captured events
hatch inspect webhooks/stripe

# 3. Search for specific event types
hatch search webhooks/stripe -query 'payment_intent.succeeded'

# 4. Replay to test handler
hatch replay <event-id> \
  -endpoint webhooks/stripe \
  -target http://localhost:3000/stripe/webhook

# 5. Configure mock for frontend testing
hatch mock set webhooks/stripe \
  -status 200 \
  -body '{"received":true}'

Load Testing

# Capture multiple events
for i in {1..10}; do
  hatch capture /webhooks/stripe \
    -body "{\"id\":\"evt_$i\",\"type\":\"payment_intent.succeeded\"}"
done

# Replay all to load test handler
hatch inspect webhooks/stripe -limit 10 | \
  jq -r '.[] | "hatch replay \(.id) -endpoint webhooks/stripe -target http://localhost:3000/stripe/webhook"' | \
  bash

Example 2: GitHub Webhook Debugging

Debug GitHub webhook delivery issues.

Capture GitHub Events

# Capture push events
hatch capture /webhooks/github \
  -method POST \
  -header 'X-GitHub-Event:push' \
  -header 'X-Hub-Signature:sha1=abc123' \
  -body '{"ref":"refs/heads/main","commits":[{"id":"def456","message":"Fix bug"}]}'

# Capture pull request events
hatch capture /webhooks/github \
  -method POST \
  -header 'X-GitHub-Event:pull_request' \
  -body '{"action":"opened","pull_request":{"number":42,"title":"New feature"}}'

Debug Failed Deliveries

# Find failed webhook deliveries
hatch search webhooks/github -query 'status:500'

# Get details of failed request
hatch inspect webhooks/github -limit 5

# Replay to local debugging server
hatch replay <request-id> \
  -endpoint webhooks/github \
  -target http://localhost:8080/debug

Mock GitHub API Responses

# Mock GitHub API for local development
hatch mock set api/github \
  -status 200 \
  -header 'Content-Type:application/json' \
  -body '{"login":"test-user","id":12345}'

Example 3: Slack Integration Testing

Test Slack app integrations without hitting real Slack APIs.

Capture Slack Events

# Capture Slack events
hatch capture /slack/events \
  -method POST \
  -header 'X-Slack-Signature:v0=abc123' \
  -body '{"type":"event_callback","event":{"type":"message","text":"Hello world"}}'

# Capture Slack interactive payloads
hatch capture /slack/actions \
  -method POST \
  -header 'X-Slack-Signature:v0=def456' \
  -body '{"type":"interactive_message","actions":[{"type":"button","value":"approve"}]}'

Development Setup

# Mock Slack API responses
hatch mock set slack/api \
  -status 200 \
  -header 'Content-Type:application/json' \
  -body '{"ok":true}'

# Test message sending
hatch replay <message-event-id> \
  -endpoint slack/events \
  -target http://localhost:3000/slack/events

Example 4: Payment Provider Integration

Test payment provider webhooks across different environments.

Multi-Environment Setup

# Development environment
hatch mock set payments/webhook \
  -status 200 \
  -body '{"status":"received"}'

# Staging environment
hatch capture payments/webhook \
  -body '{"type":"payment.completed","amount":1000,"currency":"USD"}'

# Replay to different environments
hatch replay <payment-id> \
  -endpoint payments/webhook \
  -target http://localhost:8080/payments/webhook  # Local
hatch replay <payment-id> \
  -endpoint payments/webhook \
  -target https://staging.example.com/payments/webhook  # Staging

Error Simulation

# Simulate payment failure
hatch mock set payments/webhook \
  -status 200 \
  -body '{"status":"failed","error":"insufficient_funds"}'

# Simulate network timeout (use with caution)
hatch mock set payments/webhook \
  -status 504 \
  -body '{"error":"gateway_timeout"}'

Example 5: API Documentation Generation

Generate OpenAPI documentation from real traffic patterns.

Capture API Traffic

# Capture various endpoints
hatch capture /api/users -method GET
hatch capture /api/users -method POST -body '{"name":"John Doe"}'
hatch capture /api/users/123 -method GET
hatch capture /api/users/123 -method PUT -body '{"name":"Jane Doe"}'
hatch capture /api/posts -method GET
hatch capture /api/posts -method POST -body '{"title":"Hello World"}'

Generate Documentation

# Generate OpenAPI specs for each endpoint
hatch doc generate api/users > users-api.json
hatch doc generate api/posts > posts-api.json

# Combine into single spec
jq -s '.[0] * .[1]' users-api.json posts-api.json > combined-api.json

# Serve with Swagger UI
docker run -p 8081:8080 \
  -e SWAGGER_JSON=/openapi.json \
  -v $(pwd):/usr/share/nginx/html/swagger \
  swaggerapi/swagger-ui

Example 6: Load Testing with Real Traffic

Capture and replay production traffic for load testing.

Capture Production Patterns

# Capture high-traffic endpoint
hatch capture /api/critical-path -limit 1000

# Export traffic patterns
hatch inspect api/critical-path -limit 1000 > traffic-patterns.json

Analyze Traffic

# Analyze request distribution
jq -r '.[] | "\(.method) \(.path)"' traffic-patterns.json | \
  sort | uniq -c | sort -rn

# Find slow requests (if timing data available)
jq '.[] | select(.duration > 1000)' traffic-patterns.json

# Identify error patterns
jq '.[] | select(.status >= 400)' traffic-patterns.json

Replay for Load Testing

# Create load test script
cat > load-test.sh << 'EOF'
#!/bin/bash
ENDPOINT="api/critical-path"
TARGET="https://loadtest.example.com"
REQUESTS=$(hatch inspect $ENDPOINT -limit 100)

echo "$REQUESTS" | jq -r '.[] | .id' | while read -r id; do
  echo "Replaying request $id"
  hatch replay "$id" -endpoint "$ENDPOINT" -target "$TARGET"
  sleep 0.1  # Rate limiting
done
EOF

chmod +x load-test.sh
./load-test.sh

Example 7: Mock Server for Frontend Development

Set up a comprehensive mock server for frontend development.

Create Mock Endpoints

# User API mock
hatch mock set api/users \
  -status 200 \
  -header 'Content-Type:application/json' \
  -body '[
    {"id":1,"name":"John Doe","email":"john@example.com"},
    {"id":2,"name":"Jane Smith","email":"jane@example.com"}
  ]'

# Authentication mock
hatch mock set api/auth \
  -status 200 \
  -header 'Content-Type:application/json' \
  -body '{"token":"mock-jwt-token-123","expires_in":3600}'

# Error responses
hatch mock set api/errors \
  -status 401 \
  -header 'Content-Type:application/json' \
  -body '{"error":"unauthorized","message":"Invalid credentials"}'

Frontend Integration

// Frontend code using mock API
const API_BASE = 'http://localhost:8080';

// Fetch users
const response = await fetch(`${API_BASE}/api/users`);
const users = await response.json();

// Login
const loginResponse = await fetch(`${API_BASE}/api/auth`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'user@example.com', password: 'pass' })
});

Best Practices

1. Use Descriptive Endpoint Names

# Good
hatch capture /webhooks/stripe-payments
hatch capture /api/v2/users

# Bad
hatch capture /a
hatch capture /test

2. Include Relevant Headers

# Capture with all relevant headers
hatch capture /webhooks/github \
  -header 'X-GitHub-Event:push' \
  -header 'X-Hub-Signature:sha1=abc123' \
  -header 'Content-Type:application/json'

3. Organize by Environment

# Development
hatch mock set dev/api/users -status 200 -body '[]'

# Staging
hatch mock set staging/api/users -status 200 -body '[{"id":1}]'

4. Use Search for Debugging

# Find all errors
hatch search api/webhooks -query 'status:500'

# Find specific event types
hatch search webhooks/stripe -query 'payment_intent'

5. Document Your Mocks

# Add comments to mock configuration
hatch mock set api/users \
  -status 200 \
  -header 'X-Mock-Description:Returns list of test users'

Troubleshooting

Common Issues

1. Connection refused: Ensure Hatch server is running (hatch serve)
2. Endpoint not found: Check endpoint ID with curl http://localhost:8080/v1/endpoints
3. Request not captured: Verify request format and headers
4. Mock not working: Check if mock is configured for the correct endpoint

Debug Mode

# Enable debug logging
DEBUG=true hatch serve

# Check server logs
docker logs -f hatch-container

Performance Issues

# Limit concurrent connections
hatch inspect api/heavy-endpoint -limit 10

# Use pagination for large datasets
hatch inspect api/large-dataset -limit 50