PRD Template for Webhooks

Example: "Customers build integrations by polling our API every 5 minutes, which generates 40% of our API traffic but only finds new data 3% of the time. This wastes customer infrastructure resources and introduces up to 5 minutes of latency between an event and the customer knowing about it. 12 enterprise customers have requested webhook support to trigger automated workflows in real-time. Our competitor offers webhooks for 15 event types, and it is listed as a differentiator in competitive deals."

Example: "Primary: Support webhook delivery for 10 core event types within 60 days. Reliability: 99.9% delivery success rate with at-least-once semantics. Latency: Events delivered within 5 seconds of occurrence. Developer experience: A developer can register a webhook endpoint and receive their first event within 10 minutes. Polling reduction: Reduce API polling traffic by 50%."

Example: "As a developer, I want to register a webhook URL that receives real-time notifications when a record is created or updated so that I can trigger downstream automation without polling the API. Acceptance criteria: I can register a webhook via API or UI; I can select which event types to subscribe to; each delivery includes a signature header for verification; failed deliveries are retried automatically; I can view delivery logs for debugging."

Example: "FR-1: The system must support webhooks for these event types: record.created, record.updated, record.deleted, project.published, ticket.status_changed. FR-2: Each webhook delivery must include a JSON payload with event_type, event_id (for idempotency), timestamp, and the resource data. FR-3: Each delivery must include an HMAC-SHA256 signature header for verification. FR-4: Failed deliveries (non-2xx response) must be retried 5 times with exponential backoff (1min, 5min, 30min, 2hr, 12hr). FR-5: Users must be able to view delivery logs for the last 30 days, including status, response code, and response time."

Example: "NFR-1: Webhook delivery must not impact core application latency — events are queued asynchronously. NFR-2: The system must support delivering 10,000 webhook events per minute. NFR-3: Webhook delivery must use a separate infrastructure from the main API (dedicated workers/queue). NFR-4: After all retry attempts are exhausted, the webhook endpoint must be disabled and the admin notified. NFR-5: Webhook payloads must be signed with per-endpoint HMAC secrets using SHA-256."

Example: "Metric 1: Webhook adoption (customers with active webhooks / total API consumers). Target: 40% within 6 months. Metric 2: Webhook delivery success rate. Target: 99.9%. Metric 3: Average delivery latency. Target: under 5 seconds. Metric 4: API polling traffic reduction. Baseline: 40% of API traffic. Target: under 15%. Metric 5: Webhook-related support tickets. Target: under 5/month."

Example: "Events are published to a RabbitMQ exchange when state changes occur. A webhook delivery worker consumes events, fans out to all subscribed endpoints, and delivers via HTTP POST. Each delivery attempt is logged with status code and response time. Retry logic uses exponential backoff with jitter. HMAC signatures are computed per-endpoint using a unique secret stored encrypted in the database. Delivery workers run separately from the main API to isolate failure domains."

Example: "Risk: A consumer endpoint is slow or down, causing delivery queue backup that delays all other webhooks. Likelihood: High. Impact: Medium. Mitigation: Per-endpoint delivery queues with circuit breaker — a consistently failing endpoint is paused without affecting other endpoints. Risk: An attacker registers a webhook URL pointing to an internal service (SSRF). Likelihood: Medium. Impact: High. Mitigation: Validate webhook URLs against a blocklist of private IP ranges and cloud metadata endpoints."