Priya Nair·
Tech spec for a webhook service with the signing scheme, retry backoff and the SKIP LOCKED worker
Creates comprehensive technical specification documents ready for engineering implementation with interfaces, data models, error handling, and test plans.
Technical Specification Document Generator
You are a Principal Engineer who writes technical specifications that engineering teams implement without ambiguity. Write a complete technical specification.
**Feature/System Name**: {{feature_name}}
**Purpose**: {{purpose}} (what does this feature/system do and why is it needed?)
**Scope**: {{scope}} (what's in scope and out of scope for this specification?)
**Dependencies**: {{dependencies}} (upstream/downstream systems, blocked by, blocks)
Write a complete technical specification with:
1. **Overview** - Executive summary, business context, user stories driving this technical work
2. **Goals & Success Criteria** - 3-7 specific, measurable technical goals (e.g., 'API P95 latency < 100ms at 10K RPM')
3. **Non-Goals** - Explicitly what's NOT included to prevent scope creep
4. **Architecture Diagram** - Mermaid/ASCII diagram showing all components and their interactions
5. **Data Model** - Complete entity-relationship diagram, database schema (SQL DDL), field definitions with types and constraints
6. **API Specification** - All endpoints with HTTP methods, path parameters, query parameters, request/response bodies, headers, status codes, error responses
7. **Interface Contracts** - gRPC protobuf definitions, GraphQL schemas, event schemas, or internal service interfaces
8. **Algorithms & Business Logic** - Core algorithms with pseudocode, state machines, decision trees, workflow definitions
9. **Error Handling Strategy** - Error taxonomy, error codes, retry policies, circuit breaker configuration, fallback behaviors
10. **State Management** - Application state design, session management, caching strategy, consistency model
11. **Security Considerations** - Auth requirements, input validation, output encoding, CSRF protection, rate limiting, data privacy
12. **Performance Requirements** - Latency budgets per operation, throughput targets, concurrency limits, resource utilization targets
13. **Testing Plan** - Unit test coverage targets (>80%), integration test scenarios, e2e test flows, load test scenarios
14. **Deployment Plan** - Feature flags, rollout strategy (percentage-based), rollback procedure, monitoring validation
15. **Monitoring & Alerting** - Key metrics, SLIs, SLOs, dashboard requirements, alert thresholds, runbook references
16. **Open Questions** - Unresolved questions with assigned owners and deadlines
Use precise, unambiguous language. Every requirement should be testable. Include concrete examples, not vague descriptions.
Ergebnisse
# Tech Spec: Idempotent Webhook Delivery Service
## Overview
A service that delivers events to customer-registered webhook endpoints with at-least-once semantics, signing, and automatic retries. Replaces ad-hoc `fetch`-in-a-loop calls scattered across services.
## Goals & success criteria
- Deliver 99.9% of events within 60s of emission.
- Survive endpoint downtime up to 24h without event loss.
- Webhook dispatch P95 < 150ms (enqueue time, not customer round-trip).
## Non-goals
- Customer-side endpoint reliability (their problem).
- Synchronous delivery guarantees.
## Data model
```sql
CREATE TABLE webhook_delivery (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
endpoint_id uuid NOT NULL REFERENCES webhook_endpoint(id),
event_id uuid NOT NULL,
status text NOT NULL DEFAULT 'pending', -- pending|delivered|failed
attempts int NOT NULL DEFAULT 0,
next_retry_at timestamptz,
UNIQUE (endpoint_id, event_id) -- idempotency
);
```
## API
`POST /v1/webhook-endpoints` registers an endpoint; the body returns a signing secret (shown once).
## Core logic
A worker claims due rows (`next_retry_at <= now()` `FOR UPDATE SKIP LOCKED`), POSTs the signed payload, and on failure schedules the next attempt with exponential backoff (1m, 5m, 30m, 2h, 6h) up to 8 tries.
```
signature = HMAC-SHA256(secret, timestamp + "." + rawBody)
header: Webhook-Signature: t=1717250000,v1=<hex>
```
## Error handling
Non-2xx or timeout → increment `attempts`, set `next_retry_at`. After max attempts → `failed` + alert the endpoint owner.
## Testing plan
Unit tests for backoff math and signature; integration test with a WireMock endpoint returning 500 then 200, asserting exactly one successful delivery. Load test: 10k events/min sustained.
Modell: Claude Opus 4
32 Likes13 SavesScore: 27
1 Kommentar
Ryan Mitchell·
Bookmarked — exactly the system design approach I was missing.