Outgoing webhooks
Send events to your customers' endpoints: signed payloads, retries with backoff, a delivery log and replay.
This is an app part spec on Spekkr, published by rook. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.
- Spec
rook/outgoing-webhooks- Version
- 0.1.2
- Published by
- rook
- Updated
- 15 Nov 2026
Build this spec
Build the spec at https://spekkr.com/rook/outgoing-webhooks/start.md.
Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.
Published by rook.
What does the result look like?
What can I customize?
Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.
What do I get?
-
spec.mdRequirements and acceptance criteria.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.jsonfirst. The signature travels in theheader_nameheader.auto_disabledecides whether R7 exists andsecret_rotationwhether 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
httpsaddress 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.
emitwith 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
POSTwith a JSON body, aWebhook-Idheader holding the event id, and the signature in theheader_nameheader. The signature is
t=TIME,v1=HEX.TIMEis the time of sending in seconds sinceHEXis HMAC-SHA-256, keyed with the endpoint's secret, overTIME, 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
TIMEmore than 5 minutes from their clock.
Accept when: the test vector in
design.mdproduces 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.254and[::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_disableis 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_rotationis on.- Rotating issues a new secret. For 24 hours every request carries two signatures,
v1=with the new secret and a secondv1=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.
# 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.
-
design.mdData model, rules and flows.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
databaseinput.Table Columns webhook_endpointsid,owner_id,url,event_types(empty means all),secret_encrypted,old_secret_encrypted,old_secret_until,enabled,disabled_reason,created_atwebhook_eventsid,owner_id,type,data,created_atwebhook_deliveriesid,event_id,endpoint_id,state,attempts,next_attempt_at,created_atwebhook_attemptsid,delivery_id,status,duration_ms,response_start,error,atstateis one ofwaiting,sending,deliveredandfailed.The body
{ "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-useTime 1700000000Body {"id":"evt_1","type":"invoice.paid","created":1700000000,"data":{"invoice":"inv_42"}}Signed text 1700000000.followed by the bodyHeader value t=1700000000,v1=SIGNATURESIGNATUREfor this vector is:67792ab0d3124c0722bce4f5970dcb6cc6fe52166f53af158e5146c26904dd8fIn 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_athas passed, one worker per delivery. In Postgres claim withFOR UPDATE SKIP LOCKED; in SQLite with a singleUPDATEthat setsstatetosendingwhere it iswaiting. - A delivery left in
sendingfor 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
Hostheader. 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_URLConnection string for the chosen database. WEBHOOK_ENCRYPTION_KEYEncrypts signing secrets. 32 random bytes, base64. WEBHOOK_ALLOW_LOCALSet to 1to 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.paidandping. claimed_aton 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.
# 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. - A worker loop claims deliveries whose
-
tasks.mdBuild tasks in order, each with a check.Tasks
Work in order. Finish a task's check before starting the next.
- Set up. Add the tables in
design.md. If there is no app yet, build the smallest one: a signed-in customer and one thing that changes, to emit from. Check: migrations run from empty. - Sign (R3). The signing function, using the
header_nameinput for the header. Check: a test produces the signature indesign.mdfrom the vector there. - Endpoints (R1). Create, edit, delete, with the secret encrypted. Check: the R1 acceptance tests pass.
- Emit (R2). Check: the R2 acceptance tests pass, including the rolled-back transaction.
- Check the address (R5). Check: the R5 acceptance tests pass with a resolver the tests control.
- Deliver and retry (R4). The worker loop, with a clock tests can set and a local receiver. Check: the R4 acceptance tests pass.
- Log and replay (R6). Check: the R6 acceptance tests pass.
- Failing endpoints (R7). Only if
auto_disableis on. Check: the R7 acceptance tests pass. - Rotation (R8). Only if
secret_rotationis on. Check: the R8 acceptance tests pass. - Pages (R9). Check: every page can be used with a keyboard alone and at 360 pixels wide.
- Finish. Write the README and run the whole test suite. Check: every item under "Definition of done" in
spec.mdis true.
# Tasks Work in order. Finish a task's check before starting the next. 1. **Set up.** Add the tables in `design.md`. If there is no app yet, build the smallest one: a signed-in customer and one thing that changes, to emit from. Check: migrations run from empty. 2. **Sign (R3).** The signing function, using the `header_name` input for the header. Check: a test produces the signature in `design.md` from the vector there. 3. **Endpoints (R1).** Create, edit, delete, with the secret encrypted. Check: the R1 acceptance tests pass. 4. **Emit (R2).** Check: the R2 acceptance tests pass, including the rolled-back transaction. 5. **Check the address (R5).** Check: the R5 acceptance tests pass with a resolver the tests control. 6. **Deliver and retry (R4).** The worker loop, with a clock tests can set and a local receiver. Check: the R4 acceptance tests pass. 7. **Log and replay (R6).** Check: the R6 acceptance tests pass. 8. **Failing endpoints (R7).** Only if `auto_disable` is on. Check: the R7 acceptance tests pass. 9. **Rotation (R8).** Only if `secret_rotation` is on. Check: the R8 acceptance tests pass. 10. **Pages (R9).** Check: every page can be used with a keyboard alone and at 360 pixels wide. 11. **Finish.** Write the README and run the whole test suite. Check: every item under "Definition of done" in `spec.md` is true. - Set up. Add the tables in
Is it for me?
- Kind
- app part
- Platforms
- backend, web
What does it need?
- Agent permissions
- shell, network
- Secrets it reads
DATABASE_URLWEBHOOK_ENCRYPTION_KEY
What changed?
- 0.1.215 Nov 2026Names what it builds.
- 0.1.114 Nov 2026Says "person" where it said "buyer".
- 0.1.014 Nov 2026Moved from dwrtz/outgoing-webhooks.
For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.