FastAPI Webhook Service

A production-style FastAPI service for ingesting "WhatsApp-like" messages with exactly-once processing, HMAC validation, and observability.

Features

• Ingestion: /webhook endpoint accepts JSON messages with HMAC SHA256 signature validation.
• Idempotency: Ensures exactly-once processing using message ID uniqueness.
• Retrieval: /messages endpoint with pagination and filtering.
• Analytics: /stats endpoint for simple message aggregations.
• Observability:
  • /metrics: Prometheus-style metrics.
  • /health: Liveness and Readiness probes.
  • Structured JSON logging.
• Infrastructure: Docker, Docker Compose, SQLite.

Setup & Running

Prerequisites

• Docker and Docker Compose
• Make (optional)

Running the Stack

To start the service and database:

make up
# OR
docker compose up -d --build

The API will be available at http://localhost:8000.

Configuration

Environment variables (defined in docker-compose.yml or .env):

• DATABASE_URL: Connection string (default: sqlite:////data/app.db)
• WEBHOOK_SECRET: Secret key for HMAC validation (Required).
• LOG_LEVEL: Logging level (default: INFO).

API Endpoints

POST /webhook

Ingests a message.

• Header: X-Signature: <hex HMAC-SHA256 of body>
• Body: JSON with message_id, from, to, ts, text.

GET /messages

List messages.

• Params: limit, offset, from (filter by sender), since (filter by time), q (text search).

GET /stats

Returns message anayltics.

GET /health/live & /health/ready

Health probes for Kubernetes/Orchestrators.

GET /metrics

Prometheus metrics.

Design Decisions

HMAC Verification

HMAC verification uses the standard libraries hmac and hashlib. The raw request body is read and hashed against the WEBHOOK_SECRET. Constant-time comparison (hmac.compare_digest) is used to prevent timing attacks.

Pagination

Offset/Limit pagination is implemented using SQL OFFSET and LIMIT. Default limit is 50. Warning: Deep pagination with OFFSET can be slow on large datasets; cursor-based pagination would be better for high scale but OFFSET is sufficient for requirements.

Metrics

We expose standard Prometheus metrics:

• http_requests_total: Counter by status and path.
• webhook_requests_total: Counter by result (created, duplicate, etc.).
• request_latency_ms: Histogram of request duration.

Development

Run tests locally:

# Install dependencies
pip install -r requirements.txt

# Run tests
WEBHOOK_SECRET=testsecret python -m pytest tests/ -v

Setup Used

VSCode + Agentic Coding Assistant.