# 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_inbox` | `id`, `source`, `event_id`, `event_type`, `headers` (JSON), `body` (the raw bytes), `state`, `attempts`, `next_attempt_at`, `last_error`, `received_at`, `handled_at`; unique on `source` and `event_id` | `state` is one of `waiting`, `processing`, `done`, `ignored` and `failed`. ## Signature schemes | Scheme | The header holds | The signature is | | --- | --- | --- | | `timed` | `t=TIME,v1=HEX`, with one or more `v1=` parts | HMAC-SHA-256, keyed with the secret, over `TIME`, a full stop and the body, in hexadecimal | | `plain` | `sha256=HEX` | HMAC-SHA-256, keyed with the secret, over the body, in hexadecimal | `TIME` is seconds since 1970. With several `v1=` parts, any one that matches passes. `plain` signs no time, so R2's time rule does not apply to it. ## Test vectors Both use the secret `test-secret-do-not-use` as ASCII text and this body: ``` {"id":"evt_1","type":"invoice.paid","created":1700000000,"data":{"invoice":"inv_42"}} ``` | Scheme | Header value | | --- | --- | | `timed`, at time `1700000000` | `t=1700000000,v1=67792ab0d3124c0722bce4f5970dcb6cc6fe52166f53af158e5146c26904dd8f` | | `plain` | `sha256=3e93cd005178b0844d73fac20371958a06584d8dcc5ac27ac6bfb8f57c189839` | For the `timed` vector to pass R2's time rule, the test sets the clock to `1700000000`. ## Rules - Read the body as bytes and keep them. Do not let the framework parse it first: parsing and writing it out again changes the bytes and the signature fails. - Insert the row with the unique index doing the work of R4. A conflict means the event was seen: answer 200. - A worker loop claims rows that are `waiting` with `next_attempt_at` passed, one worker per row. In Postgres claim with `FOR UPDATE SKIP LOCKED`; in SQLite with a single `UPDATE` that sets `processing` where the state is `waiting`. - A row left in `processing` for more than 5 minutes is claimable again. - The waits after failures 1 to 5 are 60, 300, 1800, 7200 and 28800 seconds. - Take the time from one function, so tests can set it. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | | `WEBHOOK_SECRET_EXAMPLE` | The example source's secret. Each source names its own variable. | ## 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 source signs as `rook/outgoing-webhooks` does, in the header `X-Webhook-Signature`. - Each failure is a row in `webhook_failures`: the event, the time, and the first 2,000 characters of the error. `claimed_at` on the inbox row says when processing began. - A request exactly `tolerance_seconds` from the clock is accepted. "Process again" runs whatever the event's state. ## 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.