hookrelay 0.2.0__tar.gz

hookrelay-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: hookrelay
+          POSTGRES_PASSWORD: hookrelay
+          POSTGRES_DB: hookrelay_test
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      redis:
+        image: redis:7
+        ports: ["6379:6379"]
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    env:
+      HOOKRELAY_TEST_DATABASE_URL: postgresql+asyncpg://hookrelay:hookrelay@localhost:5432/hookrelay_test
+      HOOKRELAY_TEST_REDIS_URL: redis://localhost:6379/0
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Type check
+        run: mypy src
+      - name: Test
+        run: pytest -v

hookrelay-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hookrelay-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.vscode/
+.idea/

hookrelay-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robson Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hookrelay-0.2.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.5
+Name: hookrelay
+Version: 0.2.0
+Summary: Reliable webhook processing for Python: automatic retries with backoff, dead-letter queue and idempotency.
+Project-URL: Homepage, https://github.com/CodeMaster-Java/hookrelay
+Project-URL: Repository, https://github.com/CodeMaster-Java/hookrelay
+Project-URL: Issues, https://github.com/CodeMaster-Java/hookrelay/issues
+Author: Robson Carvalho
+License: MIT
+License-File: LICENSE
+Keywords: asyncio,dead-letter-queue,fastapi,reliability,retry,webhook
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.19; extra == 'dev'
+Requires-Dist: asyncpg>=0.29; extra == 'dev'
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: prometheus-client>=0.20; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: redis>=5.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.20; extra == 'metrics'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.19; extra == 'sqlite'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'sqlite'
+Description-Content-Type: text/markdown
+
+# hookrelay
+
+[![CI](https://github.com/CodeMaster-java/hookrelay/actions/workflows/ci.yml/badge.svg)](https://github.com/CodeMaster-java/hookrelay/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/hookrelay.svg)](https://pypi.org/project/hookrelay/)
+[![Python versions](https://img.shields.io/pypi/pyversions/hookrelay.svg)](https://pypi.org/project/hookrelay/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Reliable webhook processing for Python: automatic retries with exponential
+backoff, a dead-letter queue for events that never succeed, and idempotency so
+duplicate deliveries are not processed twice.
+
+Webhook providers (WhatsApp/Evolution API, Stripe, GitHub, ...) fire an HTTP
+request and expect a fast response. If your handler is slow, flaky, or
+depends on another service that's temporarily down, you either block the
+request or silently drop the event. hookrelay separates *receiving* a webhook
+from *processing* it: an endpoint enqueues the event and returns immediately,
+a background worker processes it with retries, and anything that keeps
+failing lands in a dead-letter queue instead of disappearing.
+
+## Install
+
+```bash
+pip install hookrelay[fastapi,postgres]   # or [redis] / [sqlite] instead of [postgres]
+pip install hookrelay[metrics]            # optional: Prometheus metrics for Worker
+```
+
+## Quickstart (FastAPI + Postgres)
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from hookrelay import RetryPolicy, Worker
+from hookrelay.backends.postgres import PostgresBackend
+from hookrelay.fastapi import create_webhook_router
+
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
+backend = PostgresBackend(engine, retry_policy=RetryPolicy(max_attempts=5))
+
+# 1. Receive: mount a router that enqueues instead of processing inline.
+router = create_webhook_router(backend=backend, source="evolution-api")
+app.include_router(router, prefix="/webhooks/whatsapp")
+
+# 2. Process: run this as a background task or a separate process.
+async def handle(event):
+    ...  # your business logic; raise to trigger a retry
+
+worker = Worker(backend, handle)
+await worker.run_forever()
+```
+
+On startup, create the table once with `await backend.init_schema()`, or
+generate a migration from `hookrelay.backends.postgres.metadata` if your
+project manages schema through Alembic.
+
+## How it works
+
+- **Backend**: stores events and decides what's due for (re)processing.
+  `PostgresBackend` and `RedisBackend` are safe for concurrent workers;
+  `SQLiteBackend` is safe within a single process; `MemoryBackend` is for
+  local development and tests.
+- **Worker**: polls the backend, calls your handler, and acks or fails the
+  event based on whether the handler raised. `Worker(..., concurrency=N)`
+  runs up to `N` handlers from the same claimed batch at once, bounded by an
+  `asyncio.Semaphore`; each event is still individually acked or failed, so
+  the retry and dead-letter contract doesn't change.
+- **RetryPolicy**: exponential backoff with jitter (`base_delay * multiplier
+  ** attempt`, capped at `max_delay`), shared by every backend so retry
+  behavior doesn't depend on which one you picked.
+- **Idempotency**: pass `idempotency_key` when building a `WebhookEvent` (or
+  an `idempotency_key` extractor to `create_webhook_router`) and a second
+  delivery with the same key is a no-op.
+- **Dead-letter queue**: once `max_attempts` is exhausted, an event moves to
+  `EventStatus.DEAD_LETTER`. Inspect it with `backend.list_dead_letters()`
+  and retry it manually with `backend.requeue_dead_letter(event_id)`, or
+  from the command line with `hookrelay dead-letters list|requeue` (see
+  below).
+- **Metrics**: pass a `WorkerMetrics` implementation to `Worker(...,
+  metrics=...)` for counters of processed, retried, and dead-lettered events
+  plus a handler-duration histogram. `hookrelay.metrics.PrometheusMetrics`
+  is a ready-made one (requires the `metrics` extra); implement the
+  `WorkerMetrics` protocol yourself to plug into anything else.
+
+## Choosing a backend
+
+| | Postgres | Redis | SQLite | Memory |
+|---|---|---|---|---|
+| Multiple workers | Yes (`SELECT ... FOR UPDATE SKIP LOCKED`) | Yes, for modest concurrency | No (single process only) | No |
+| Recovers a worker that crashes mid-processing | Yes | Yes, call `reap_stale_claims()` periodically | No | No |
+| Extra infra required | Postgres (you probably already have it) | Redis | None (a local file) | None |
+
+If you're unsure, start with Postgres: you likely already run one, and it
+gives you the strongest guarantees. `SQLiteBackend` is a good fit for a
+single-process deployment or script where standing up Postgres or Redis just
+for retry bookkeeping isn't worth it.
+
+## Maintenance
+
+Two housekeeping operations are opt-in: hookrelay never runs them on its own,
+so wire them into whatever periodic task runner you already use (a cron job,
+an `asyncio` task, ...).
+
+- **`RedisBackend.reap_stale_claims()`**: a claimed event carries a lease
+  (`claim_lease_seconds`, default 300). If the worker that claimed it
+  crashes before acking or failing it, the event is stuck until you call
+  `reap_stale_claims()`, which requeues it (or dead-letters it, if that was
+  its last attempt) exactly like any other failure. Call it every
+  `claim_lease_seconds / 2` or so.
+- **`PostgresBackend.purge()` / `SQLiteBackend.purge()`**: successful and
+  dead-lettered events stay in the table indefinitely otherwise. Call
+  `backend.purge(older_than=some_datetime)` periodically to delete them past
+  a retention window you choose.
+
+## CLI
+
+Installing hookrelay also installs a `hookrelay` command for inspecting and
+recovering dead-lettered events against a running deployment:
+
+```bash
+hookrelay dead-letters list --backend postgresql+asyncpg://user:pass@localhost/db
+hookrelay dead-letters requeue <event-id> --backend redis://localhost:6379/0
+```
+
+`--backend` accepts a Postgres, Redis, or SQLite URL; the CLI picks the
+matching backend implementation from its scheme and only needs that
+backend's extra installed.
+
+## Known limitations
+
+- There's no built-in dashboard for dead-letter events; `list_dead_letters()`,
+  `requeue_dead_letter()`, and the `hookrelay dead-letters` CLI are meant to
+  be wired into your own admin tooling, not to replace it.
+- `SQLiteBackend` is safe for concurrent calls within one process (guarded
+  by an internal lock) but not for multiple worker processes writing to the
+  same database file; use `PostgresBackend` if you need that.
+
+## Roadmap
+
+Planned improvements and deliberate non-goals live in [ROADMAP.md](ROADMAP.md).
+
+## Example
+
+See [`examples/evolution_api_whatsapp`](examples/evolution_api_whatsapp) for a
+complete FastAPI app that receives Evolution API (self-hosted WhatsApp)
+webhooks with signature verification and idempotency.
+
+## Contributing
+
+Issues and PRs are welcome. Run the test suite with:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Postgres- and Redis-backed tests are skipped automatically unless
+`HOOKRELAY_TEST_DATABASE_URL` and `HOOKRELAY_TEST_REDIS_URL` are set; see
+`.github/workflows/ci.yml` for how CI provides both.
+
+## License
+
+MIT

hookrelay-0.2.0/README.md

@@ -0,0 +1,161 @@
+# hookrelay
+
+[![CI](https://github.com/CodeMaster-java/hookrelay/actions/workflows/ci.yml/badge.svg)](https://github.com/CodeMaster-java/hookrelay/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/hookrelay.svg)](https://pypi.org/project/hookrelay/)
+[![Python versions](https://img.shields.io/pypi/pyversions/hookrelay.svg)](https://pypi.org/project/hookrelay/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Reliable webhook processing for Python: automatic retries with exponential
+backoff, a dead-letter queue for events that never succeed, and idempotency so
+duplicate deliveries are not processed twice.
+
+Webhook providers (WhatsApp/Evolution API, Stripe, GitHub, ...) fire an HTTP
+request and expect a fast response. If your handler is slow, flaky, or
+depends on another service that's temporarily down, you either block the
+request or silently drop the event. hookrelay separates *receiving* a webhook
+from *processing* it: an endpoint enqueues the event and returns immediately,
+a background worker processes it with retries, and anything that keeps
+failing lands in a dead-letter queue instead of disappearing.
+
+## Install
+
+```bash
+pip install hookrelay[fastapi,postgres]   # or [redis] / [sqlite] instead of [postgres]
+pip install hookrelay[metrics]            # optional: Prometheus metrics for Worker
+```
+
+## Quickstart (FastAPI + Postgres)
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from hookrelay import RetryPolicy, Worker
+from hookrelay.backends.postgres import PostgresBackend
+from hookrelay.fastapi import create_webhook_router
+
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
+backend = PostgresBackend(engine, retry_policy=RetryPolicy(max_attempts=5))
+
+# 1. Receive: mount a router that enqueues instead of processing inline.
+router = create_webhook_router(backend=backend, source="evolution-api")
+app.include_router(router, prefix="/webhooks/whatsapp")
+
+# 2. Process: run this as a background task or a separate process.
+async def handle(event):
+    ...  # your business logic; raise to trigger a retry
+
+worker = Worker(backend, handle)
+await worker.run_forever()
+```
+
+On startup, create the table once with `await backend.init_schema()`, or
+generate a migration from `hookrelay.backends.postgres.metadata` if your
+project manages schema through Alembic.
+
+## How it works
+
+- **Backend**: stores events and decides what's due for (re)processing.
+  `PostgresBackend` and `RedisBackend` are safe for concurrent workers;
+  `SQLiteBackend` is safe within a single process; `MemoryBackend` is for
+  local development and tests.
+- **Worker**: polls the backend, calls your handler, and acks or fails the
+  event based on whether the handler raised. `Worker(..., concurrency=N)`
+  runs up to `N` handlers from the same claimed batch at once, bounded by an
+  `asyncio.Semaphore`; each event is still individually acked or failed, so
+  the retry and dead-letter contract doesn't change.
+- **RetryPolicy**: exponential backoff with jitter (`base_delay * multiplier
+  ** attempt`, capped at `max_delay`), shared by every backend so retry
+  behavior doesn't depend on which one you picked.
+- **Idempotency**: pass `idempotency_key` when building a `WebhookEvent` (or
+  an `idempotency_key` extractor to `create_webhook_router`) and a second
+  delivery with the same key is a no-op.
+- **Dead-letter queue**: once `max_attempts` is exhausted, an event moves to
+  `EventStatus.DEAD_LETTER`. Inspect it with `backend.list_dead_letters()`
+  and retry it manually with `backend.requeue_dead_letter(event_id)`, or
+  from the command line with `hookrelay dead-letters list|requeue` (see
+  below).
+- **Metrics**: pass a `WorkerMetrics` implementation to `Worker(...,
+  metrics=...)` for counters of processed, retried, and dead-lettered events
+  plus a handler-duration histogram. `hookrelay.metrics.PrometheusMetrics`
+  is a ready-made one (requires the `metrics` extra); implement the
+  `WorkerMetrics` protocol yourself to plug into anything else.
+
+## Choosing a backend
+
+| | Postgres | Redis | SQLite | Memory |
+|---|---|---|---|---|
+| Multiple workers | Yes (`SELECT ... FOR UPDATE SKIP LOCKED`) | Yes, for modest concurrency | No (single process only) | No |
+| Recovers a worker that crashes mid-processing | Yes | Yes, call `reap_stale_claims()` periodically | No | No |
+| Extra infra required | Postgres (you probably already have it) | Redis | None (a local file) | None |
+
+If you're unsure, start with Postgres: you likely already run one, and it
+gives you the strongest guarantees. `SQLiteBackend` is a good fit for a
+single-process deployment or script where standing up Postgres or Redis just
+for retry bookkeeping isn't worth it.
+
+## Maintenance
+
+Two housekeeping operations are opt-in: hookrelay never runs them on its own,
+so wire them into whatever periodic task runner you already use (a cron job,
+an `asyncio` task, ...).
+
+- **`RedisBackend.reap_stale_claims()`**: a claimed event carries a lease
+  (`claim_lease_seconds`, default 300). If the worker that claimed it
+  crashes before acking or failing it, the event is stuck until you call
+  `reap_stale_claims()`, which requeues it (or dead-letters it, if that was
+  its last attempt) exactly like any other failure. Call it every
+  `claim_lease_seconds / 2` or so.
+- **`PostgresBackend.purge()` / `SQLiteBackend.purge()`**: successful and
+  dead-lettered events stay in the table indefinitely otherwise. Call
+  `backend.purge(older_than=some_datetime)` periodically to delete them past
+  a retention window you choose.
+
+## CLI
+
+Installing hookrelay also installs a `hookrelay` command for inspecting and
+recovering dead-lettered events against a running deployment:
+
+```bash
+hookrelay dead-letters list --backend postgresql+asyncpg://user:pass@localhost/db
+hookrelay dead-letters requeue <event-id> --backend redis://localhost:6379/0
+```
+
+`--backend` accepts a Postgres, Redis, or SQLite URL; the CLI picks the
+matching backend implementation from its scheme and only needs that
+backend's extra installed.
+
+## Known limitations
+
+- There's no built-in dashboard for dead-letter events; `list_dead_letters()`,
+  `requeue_dead_letter()`, and the `hookrelay dead-letters` CLI are meant to
+  be wired into your own admin tooling, not to replace it.
+- `SQLiteBackend` is safe for concurrent calls within one process (guarded
+  by an internal lock) but not for multiple worker processes writing to the
+  same database file; use `PostgresBackend` if you need that.
+
+## Roadmap
+
+Planned improvements and deliberate non-goals live in [ROADMAP.md](ROADMAP.md).
+
+## Example
+
+See [`examples/evolution_api_whatsapp`](examples/evolution_api_whatsapp) for a
+complete FastAPI app that receives Evolution API (self-hosted WhatsApp)
+webhooks with signature verification and idempotency.
+
+## Contributing
+
+Issues and PRs are welcome. Run the test suite with:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Postgres- and Redis-backed tests are skipped automatically unless
+`HOOKRELAY_TEST_DATABASE_URL` and `HOOKRELAY_TEST_REDIS_URL` are set; see
+`.github/workflows/ci.yml` for how CI provides both.
+
+## License
+
+MIT

hookrelay-0.2.0/ROADMAP.md

@@ -0,0 +1,43 @@
+# Roadmap
+
+Everything that was tracked here for v0.1 (stale-claim recovery for
+`RedisBackend`, retention/cleanup for `PostgresBackend` and `SQLiteBackend`,
+Prometheus metrics, a dead-letters CLI, concurrent handler execution, and a
+`SQLiteBackend`) shipped in v0.2. See the README's "How it works",
+"Maintenance", and "CLI" sections for how to use them.
+
+## Ideas for v0.3
+
+- **Rate limiting / throttling in `Worker`.** Nothing today bounds how fast
+  claimed events are handed to the handler; a burst of due events can drive
+  a handler straight into a downstream provider's own rate limit. A
+  configurable throttle, for example `Worker(..., max_calls_per_second=N)`,
+  following the same pattern `concurrency` already established, would let a
+  handler that calls a rate-limited API stay under it without building that
+  logic itself.
+- **Framework adapters beyond FastAPI.**
+  `hookrelay.fastapi.create_webhook_router()` is a thin adapter over
+  `Backend.enqueue()` (verify signature, parse body, enqueue, return); the
+  same shape applies just as well to Flask and Django. Adapters for those
+  two would widen who can adopt hookrelay without touching the
+  Backend/Worker contract at all.
+
+Nothing here is committed to a timeline; this is a place to track what's
+deliberately left out of the current release and why, so scope stays
+honest instead of growing by accident.
+
+## Non-goals (for now)
+
+- A hosted dashboard/UI. `list_dead_letters()` and `requeue_dead_letter()`
+  (and the `hookrelay dead-letters` CLI) are meant to be wired into whatever
+  admin tooling a project already has; building a UI is a much bigger
+  surface area than this library's scope.
+- Distributed leader election or exactly-once delivery guarantees beyond
+  what each backend's native atomicity already provides. hookrelay aims for
+  at-least-once delivery with idempotency as the tool for deduplication,
+  not a distributed consensus system.
+- Anything about the HTTP requests a handler makes, like SSRF protection or
+  HMAC-signing outgoing payloads. hookrelay only receives webhooks; `Worker`
+  calls the Python handler function you write, it never makes an HTTP
+  request on your behalf. Those concerns belong to your handler's own HTTP
+  client, not to hookrelay.

hookrelay-0.2.0/examples/evolution_api_whatsapp/README.md

@@ -0,0 +1,43 @@
+# Example: reliable WhatsApp webhooks from Evolution API
+
+Evolution API posts a JSON body like this for every event (`messages.upsert`,
+`connection.update`, etc.):
+
+```json
+{
+  "event": "messages.upsert",
+  "instance": "my-instance",
+  "data": { "key": { "id": "...", "remoteJid": "..." }, "message": { "conversation": "hi" } },
+  "server_url": "https://your-evolution-api.example.com",
+  "apikey": "your-instance-token",
+  "date_time": "2026-08-26T12:00:00.000Z"
+}
+```
+
+This example shows the pattern for making that reliable:
+
+1. Configure the instance's webhook with a custom `Authorization: Bearer <secret>`
+   header (Evolution API's webhook settings support custom headers per instance).
+2. `main.py` verifies that header, enqueues the event into Postgres via
+   `hookrelay`, and returns immediately.
+3. A background `Worker` processes events, retrying with backoff on failure and
+   moving anything that exhausts its retries to the dead-letter queue.
+4. `data.key.id` (the WhatsApp message id) is used as the idempotency key, so a
+   webhook Evolution API resends after a timeout isn't processed twice.
+
+## Run it
+
+```bash
+pip install "hookrelay[fastapi,postgres]" uvicorn
+export WEBHOOK_SHARED_SECRET=change-me
+export DATABASE_URL=postgresql+asyncpg://user:pass@localhost/hookrelay
+uvicorn main:app --reload
+```
+
+Point your Evolution API instance's webhook at
+`http://your-host:8000/webhooks/whatsapp` with the header above, and inspect
+anything that ends up dead-lettered with:
+
+```python
+await backend.list_dead_letters()
+```

hookrelay-0.2.0/examples/evolution_api_whatsapp/main.py

@@ -0,0 +1,87 @@
+"""FastAPI app that receives WhatsApp webhooks from a self-hosted Evolution API
+instance reliably: the endpoint only enqueues, a worker processes with retries,
+and messages that never process successfully land in the dead-letter queue
+instead of vanishing.
+
+Run:
+    export WEBHOOK_SHARED_SECRET=change-me
+    export DATABASE_URL=postgresql+asyncpg://user:pass@localhost/hookrelay
+    uvicorn main:app --reload
+
+Then, in your Evolution API instance settings, point the instance's webhook at
+this app's /webhooks/whatsapp URL and add a custom header
+`Authorization: Bearer change-me` to the webhook configuration.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hmac
+import logging
+import os
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import FastAPI
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from hookrelay import RetryPolicy, Worker
+from hookrelay.backends.postgres import PostgresBackend
+from hookrelay.fastapi import create_webhook_router
+
+logger = logging.getLogger("evolution_webhook_example")
+
+WEBHOOK_SHARED_SECRET = os.environ["WEBHOOK_SHARED_SECRET"]
+DATABASE_URL = os.environ["DATABASE_URL"]
+
+engine = create_async_engine(DATABASE_URL)
+backend = PostgresBackend(engine, retry_policy=RetryPolicy(max_attempts=5, base_delay=2.0))
+
+
+def verify_signature(_body: bytes, headers: Any) -> bool:
+    expected = f"Bearer {WEBHOOK_SHARED_SECRET}"
+    return hmac.compare_digest(headers.get("authorization", ""), expected)
+
+
+def extract_idempotency_key(payload: dict[str, Any]) -> str | None:
+    # WhatsApp message ids are unique per message; Evolution API resends the same
+    # message.upsert event on transient delivery failures, so this dedupes retries
+    # coming from Evolution API itself, on top of hookrelay's own retry/DLQ.
+    return payload.get("data", {}).get("key", {}).get("id")
+
+
+async def handle_whatsapp_event(event) -> None:
+    payload = event.payload
+    event_type = payload.get("event")
+
+    if event_type == "messages.upsert":
+        message = payload["data"]
+        text = message.get("message", {}).get("conversation", "<non-text message>")
+        logger.info("WhatsApp message from %s: %s", message.get("key", {}).get("remoteJid"), text)
+        # your business logic here: persist the message, trigger a bot reply, etc.
+        # raising an exception causes hookrelay to retry this event with backoff.
+    else:
+        logger.debug("ignoring event type %s", event_type)
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI):
+    await backend.init_schema()
+    worker = Worker(backend, handle_whatsapp_event)
+    worker_task = asyncio.create_task(worker.run_forever())
+    yield
+    worker.stop()
+    await worker_task
+    await engine.dispose()
+
+
+app = FastAPI(lifespan=lifespan)
+app.include_router(
+    create_webhook_router(
+        backend=backend,
+        source="evolution-api",
+        verify_signature=verify_signature,
+        idempotency_key=extract_idempotency_key,
+    ),
+    prefix="/webhooks/whatsapp",
+)