# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## Data model Use the database in the `database` input. | Table | Columns | | --- | --- | | `webhook_endpoints` | `id`, `owner_id`, `url`, `event_types` (empty means all), `secret_encrypted`, `old_secret_encrypted`, `old_secret_until`, `enabled`, `disabled_reason`, `created_at` | | `webhook_events` | `id`, `owner_id`, `type`, `data`, `created_at` | | `webhook_deliveries` | `id`, `event_id`, `endpoint_id`, `state`, `attempts`, `next_attempt_at`, `created_at` | | `webhook_attempts` | `id`, `delivery_id`, `status`, `duration_ms`, `response_start`, `error`, `at` | `state` is one of `waiting`, `sending`, `delivered` and `failed`. ## The body ```json { "id": "evt_1", "type": "invoice.paid", "created": 1700000000, "data": { "invoice": "inv_42" } } ``` Serialise the body once, store those bytes with the delivery or rebuild them the same way every time, and sign the bytes that are sent. ## Signature test vector | Part | Value | | --- | --- | | Secret, as ASCII text | `test-secret-do-not-use` | | Time | `1700000000` | | Body | `{"id":"evt_1","type":"invoice.paid","created":1700000000,"data":{"invoice":"inv_42"}}` | | Signed text | `1700000000.` followed by the body | | Header value | `t=1700000000,v1=SIGNATURE` | `SIGNATURE` for this vector is: ``` 67792ab0d3124c0722bce4f5970dcb6cc6fe52166f53af158e5146c26904dd8f ``` In use, the key is the endpoint's 32 secret bytes, shown to the customer in base64. ## Sending - A worker loop claims deliveries whose `next_attempt_at` has passed, one worker per delivery. In Postgres claim with `FOR UPDATE SKIP LOCKED`; in SQLite with a single `UPDATE` that sets `state` to `sending` where it is `waiting`. - A delivery left in `sending` for more than 2 minutes is claimable again. - The waits after failed attempts 1 to 6 are 60, 300, 1800, 7200, 28800 and 86400 seconds. Take the time from one function, so tests can set it. - Encrypt secrets with AES-256-GCM under `WEBHOOK_ENCRYPTION_KEY`, with a fresh random nonce stored next to each. - Delete events, deliveries and attempts older than 30 days once a day. ## Checking the address Resolve the host yourself, check every address returned, and hand the checked address to the HTTP client with the original host name kept for TLS and the `Host` header. Refuse these ranges: `0.0.0.0/8`, `10.0.0.0/8`, `100.64.0.0/10`, `127.0.0.0/8`, `169.254.0.0/16`, `172.16.0.0/12`, `192.168.0.0/16`, `::1`, `fc00::/7`, `fe80::/10`, and IPv4 addresses written inside IPv6. Tests need to reach a local receiver. Allow that with the environment variable `WEBHOOK_ALLOW_LOCAL=1`. It is off by default, lets through loopback addresses only, and the app refuses to start with it in production. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | | `WEBHOOK_ENCRYPTION_KEY` | Encrypts signing secrets. 32 random bytes, base64. | | `WEBHOOK_ALLOW_LOCAL` | Set to `1` to let tests reach a local receiver. It is off by default, lets through loopback addresses only, and the app refuses to start with it in production. | ## Who is signed in The spec reaches the app's sign-in through one function, `current_user(request)`. It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session. When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production. ## Named here - The example event types are `invoice.created`, `invoice.paid` and `ping`. - `claimed_at` on a delivery says when sending began. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.