# Outgoing webhooks ## What this builds A way for an app to tell its customers' servers that something happened. A customer registers an address. The app records events as they happen, sends each one to the addresses that asked for it, signs it, retries when the other side is down, and keeps a log the customer can read and replay from. Read `spekkr.inputs.json` first. The signature travels in the `header_name` header. `auto_disable` decides whether R7 exists and `secret_rotation` whether R8 does. This spec needs the app to know who is signed in on its pages, so that a customer can manage endpoints. It does not build sign-in. ## Out of scope - Receiving webhooks from other services. - Delivery in order. Events carry a time, and receivers must not assume order. - Exactly-once delivery. Receivers get each event at least once and tell repeats apart by the event id. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Endpoints - A customer adds an endpoint: an `https` address and the event types it wants, or all of them. - Each endpoint gets its own signing secret, 32 random bytes, stored encrypted. The customer can see it again on the endpoint's page. - A customer has at most 10 endpoints. - An address that is not `https`, has a username or password in it, or is longer than 2,000 characters is refused. Accept when: a valid endpoint is saved, each kind of bad address is refused with a message next to the field, and the stored secret cannot be read without `WEBHOOK_ENCRYPTION_KEY`. ### R2. Record an event - App code calls `emit(type, data)`. The event is written in the same database transaction as the change it reports, so an event exists exactly when the change was committed. - An event has an id, a type such as `invoice.paid`, a creation time and the data. - One delivery is created for each enabled endpoint that asked for the type. - Event types are a fixed list in code. `emit` with a type that is not in the list is an error. Accept when: a rolled-back transaction leaves no event, a committed one leaves one event and one delivery per subscribed endpoint, and an endpoint that did not ask for the type gets none. ### R3. Sign every request - The request is a `POST` with a JSON body, a `Webhook-Id` header holding the event id, and the signature in the `header_name` header. - The signature is `t=TIME,v1=HEX`. `TIME` is the time of sending in seconds since 1970. `HEX` is HMAC-SHA-256, keyed with the endpoint's secret, over `TIME`, a full stop and the exact bytes of the body. - The README tells receivers to recompute the signature, compare in constant time, and refuse a `TIME` more than 5 minutes from their clock. Accept when: the test vector in `design.md` produces the signature given there, and a body changed by one byte produces a different one. ### R4. Deliver and retry - A delivery succeeds when the answer has a status from 200 to 299 inside 10 seconds. Anything else is a failed attempt. Redirects are not followed. - After a failed attempt the delivery waits and tries again: after 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours and 24 hours. After the seventh failed attempt it is marked failed and left alone. - Each attempt records the status, the time it took and the first 1,000 characters of the answer. - Delivery happens outside the request that caused the event. A slow endpoint never slows the app. - No more than 5 deliveries are in flight to one endpoint at a time. Accept when: a receiver that fails twice then answers 200 gets three attempts with the right waits, a receiver that always fails gets seven and no more, and a receiver that takes 11 seconds counts as failed. ### R5. Do not let an endpoint reach inside - Before each attempt the host is resolved, and the attempt is refused if any address is loopback, private, link-local or otherwise not public. The connection is then made to the address that was checked, not resolved a second time. - Only ports 443 and 8443 are allowed. Accept when: endpoints that resolve to `127.0.0.1`, `10.0.0.5`, `169.254.169.254` and `[::1]` are each refused without a connection being opened. ### R6. Delivery log and replay - An endpoint's page lists its deliveries for the last 30 days: event type, time, state, number of attempts, and each attempt's status and duration. - The customer can open a delivery to see the body that was sent and the start of each answer. - "Send again" delivers the same event, with the same id and body and a new signature, as a new delivery. - "Send a test event" sends an event of type `ping`. Accept when: a replayed delivery carries the original event id, and one customer can never read another customer's deliveries. ### R7. Endpoints that keep failing Only if `auto_disable` is on. - An endpoint whose every attempt has failed for 5 days, with at least 20 attempts in that time, is disabled. Its waiting deliveries are marked failed. - The endpoint's page says when and why, and has a button to turn it back on. Accept when: an endpoint is disabled after 5 days of failures and not after 5 days that include one success. ### R8. Rotate the secret Only if `secret_rotation` is on. - Rotating issues a new secret. For 24 hours every request carries two signatures, `v1=` with the new secret and a second `v1=` with the old one, separated by a comma. - After 24 hours only the new secret signs. Accept when: during the 24 hours a receiver that knows either secret can verify the request, and afterwards only one that knows the new secret can. ### R9. Pages - Endpoints list, add and edit endpoint, the endpoint page with its secret and log, and the delivery page. Accept when: each page works with a keyboard alone and at a 360 pixel wide screen. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests use a local receiver, a clock that can be set, and no outside network. - No log line contains a signing secret. - A README explains how to emit an event, how a receiver verifies a signature, and how to run the tests.