Document Webhook Integrations

This skill creates comprehensive, developer-friendly webhook documentation with clear examples, detailed payload schemas, authentication methods, delivery guarantees, and troubleshooting guides. Essential components cover an overview of when and why webhooks trigger, endpoint requirements, payload schemas with types and required fields, authentication mechanisms, delivery semantics (retries, ordering, failure handling), and testing guidance - organized as progressive disclosure from a quick-start guide through a complete event reference, advanced topics, and troubleshooting.

Event documentation follows a fixed structure per webhook: when it triggers, its JSON payload schema, and per-field descriptions of type, requirement, and meaning - using realistic example values rather than generic placeholders and documenting null and empty-array handling explicitly. Authentication guidance provides a working HMAC-SHA256 signature verification function and a Node.js endpoint implementation template that verifies request timestamp (to prevent replay attacks), verifies the signature, parses the payload, and processes the event idempotently. Response-code documentation maps 2xx to success, 4xx to a non-retried client error, 5xx to a retried server error, and timeouts (10 seconds) to a retry.

Delivery and reliability guidance documents an exponential-backoff retry schedule (five attempts over roughly 15 seconds), failed-webhook retention for manual retry, and automatic endpoint disabling after 100 consecutive failures. Idempotency guidance uses the webhook's event ID to detect and skip already-processed deliveries. Testing guidance covers CLI testing with curl, third-party testing services like ngrok and webhook.site, and downloadable mock payloads per event type. Advanced configuration covers event filtering and subscription scoping, and delivery constraints (a 100 requests/second rate limit, batching up to 100 events per request, chronological ordering within an event type). The troubleshooting guide names five common issues - signature failures, timeouts, duplicate events, missing events, SSL certificate errors - each with a specific fix.

def verify_webhook_signature(payload, signature, secret):
    """
    Verify webhook signature using HMAC-SHA256
    
    Args:
        payload (bytes): Raw request body
        signature (str): Signature from X-Webhook-Signature header
        secret (str): Your webhook signing secret
    
    Returns:
        bool: True if signature is valid
    """
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    if signature.startswith('sha256='):
        signature = signature[7:]
    
    return hmac.compare_digest(expected_signature, signature)

Use this skill when documenting a webhook system for external developers - writing event schemas, documenting signature verification and replay protection, specifying retry and idempotency behavior, or building a troubleshooting guide.

It is not a fit for designing the webhook delivery infrastructure itself - it's scoped to documenting an already-built webhook system clearly, not to architecting the queue, retry engine, or delivery infrastructure behind it.

Inputs are your webhook events, their payload structures, and your authentication and retry implementation. Outputs are structured event documentation with schemas and field descriptions, signature-verification code examples, endpoint implementation templates, retry and idempotency documentation, testing guidance, and a troubleshooting guide.

API and developer-experience teams documenting webhook integrations who need a complete, structured documentation format - payload schemas with realistic examples, working signature-verification code, explicit retry and idempotency semantics, and named troubleshooting fixes - rather than an underspecified webhook reference that leaves integrators guessing at delivery guarantees.