Incoming webhooks
Receive webhooks from other services: verify the signature, answer fast, process each event once, and replay what failed.
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/incoming-webhooks- Version
- 0.1.2
- Published by
- rook
- Updated
- 15 Nov 2026
Build this spec
Build the spec at https://spekkr.com/rook/incoming-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.Incoming webhooks
What this builds
The receiving end for webhooks that other services send an app: a payment provider, a code host, an email service. Each request is checked against its signature, stored, answered at once, and processed afterwards exactly once, with retries when processing fails.
Read
spekkr.inputs.jsonfirst. A signed time may betolerance_secondsseconds off the clock.dashboarddecides whether R8 exists.Out of scope
- Sending webhooks.
spekkr/outgoing-webhooksbuilds that, and the first signature scheme here is the one it sends. - The handlers for any one service's events. The spec builds one example source and one example handler.
Requirements
Each requirement has an id. Tests name the id they cover.
R1. Sources
- A source is a service that sends webhooks. Sources are a list in code: a name, a signature scheme from
design.md, the header the signature comes in, the environment variable that holds the secret, and where in the body the event's id and type are. - Each source has its own address,
POST /webhooks/NAME. A name that is not in the list gets 404. - The example source is called
exampleand uses the schemetimed.
Accept when: a request to an unknown name gets 404 and stores nothing.
R2. Check the signature
- The signature is checked against the raw bytes of the body, before the body is parsed.
- Signatures are compared in constant time.
- For a scheme that signs a time, a request whose time is more than
tolerance_secondsseconds from the clock is refused, even with a good signature. - A source can have two secrets, the second in a variable with
_OLDadded, so a secret can be changed without losing events. A signature made with either passes. - A request that fails gets status 400 and is not stored. Why it failed is logged without the secret or the signature.
Accept when: both test vectors in
design.mdpass, a body changed by one byte fails, a good signature with a time 301 seconds old fails, and a signature made with the old secret passes.R3. Store and answer
- A request that passes is stored with its source, the event's id and type, its headers and its raw body, and answered with status 200 and an empty body.
- Nothing else happens before the answer. Handlers run afterwards.
- A body over 1 MB (1,000,000 bytes) gets status 413.
Accept when: a handler that takes 10 seconds does not delay the answer.
R4. Once
- An event is known by its source and its id. A second request with the same two is answered with 200 and neither stored nor processed again.
- A source whose events carry no id uses the SHA-256 of the body.
Accept when: the same event sent 5 times at once is stored once and its handler runs once.
R5. Handlers
- A handler is registered for a source and an event type. An event with no handler is stored and marked ignored.
- A handler gets the parsed body and the time the event says it happened. It must not assume events arrive in the order they happened.
- The example handler counts the events it has seen.
Accept when: an event of a type with no handler is marked ignored and nothing fails.
R6. Retry
- A handler that raises an error is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 8 hours. After the sixth failure the event is marked failed.
- Each failure stores the first 2,000 characters of the error.
- An event being processed when the process dies is processed again. That counts as an attempt.
Accept when: a handler that fails twice and then succeeds is run three times with waits of 60 and 300 seconds, and one that always fails is run six times.
R7. Keeping and forgetting
- Events are kept for 30 days and then deleted, bodies and all.
Accept when: a clean-up run deletes exactly the events that are old enough.
R8. Dashboard
Only if
dashboardis on.- A list of events: source, type, when, state and attempts, newest first, with a filter for each source and each state.
- One event's page shows its headers, its body and each failure.
- "Process again" runs the handler once more, whatever the state.
- Only administrators reach it. Bodies can hold personal data.
Accept when: "Process again" on a failed event runs its handler, and a person who is not an administrator gets 403.
Definition of done
- Every acceptance check above has an automated test, and all tests pass. Tests set the clock and use no outside network.
- No log line holds a secret or a whole signature.
- A README explains how to add a source and a handler, how to change a secret without losing events, and how to run the tests.
# Incoming webhooks ## What this builds The receiving end for webhooks that other services send an app: a payment provider, a code host, an email service. Each request is checked against its signature, stored, answered at once, and processed afterwards exactly once, with retries when processing fails. Read `spekkr.inputs.json` first. A signed time may be `tolerance_seconds` seconds off the clock. `dashboard` decides whether R8 exists. ## Out of scope - Sending webhooks. `spekkr/outgoing-webhooks` builds that, and the first signature scheme here is the one it sends. - The handlers for any one service's events. The spec builds one example source and one example handler. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Sources - A source is a service that sends webhooks. Sources are a list in code: a name, a signature scheme from `design.md`, the header the signature comes in, the environment variable that holds the secret, and where in the body the event's id and type are. - Each source has its own address, `POST /webhooks/NAME`. A name that is not in the list gets 404. - The example source is called `example` and uses the scheme `timed`. Accept when: a request to an unknown name gets 404 and stores nothing. ### R2. Check the signature - The signature is checked against the raw bytes of the body, before the body is parsed. - Signatures are compared in constant time. - For a scheme that signs a time, a request whose time is more than `tolerance_seconds` seconds from the clock is refused, even with a good signature. - A source can have two secrets, the second in a variable with `_OLD` added, so a secret can be changed without losing events. A signature made with either passes. - A request that fails gets status 400 and is not stored. Why it failed is logged without the secret or the signature. Accept when: both test vectors in `design.md` pass, a body changed by one byte fails, a good signature with a time 301 seconds old fails, and a signature made with the old secret passes. ### R3. Store and answer - A request that passes is stored with its source, the event's id and type, its headers and its raw body, and answered with status 200 and an empty body. - Nothing else happens before the answer. Handlers run afterwards. - A body over 1 MB (1,000,000 bytes) gets status 413. Accept when: a handler that takes 10 seconds does not delay the answer. ### R4. Once - An event is known by its source and its id. A second request with the same two is answered with 200 and neither stored nor processed again. - A source whose events carry no id uses the SHA-256 of the body. Accept when: the same event sent 5 times at once is stored once and its handler runs once. ### R5. Handlers - A handler is registered for a source and an event type. An event with no handler is stored and marked ignored. - A handler gets the parsed body and the time the event says it happened. It must not assume events arrive in the order they happened. - The example handler counts the events it has seen. Accept when: an event of a type with no handler is marked ignored and nothing fails. ### R6. Retry - A handler that raises an error is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 8 hours. After the sixth failure the event is marked failed. - Each failure stores the first 2,000 characters of the error. - An event being processed when the process dies is processed again. That counts as an attempt. Accept when: a handler that fails twice and then succeeds is run three times with waits of 60 and 300 seconds, and one that always fails is run six times. ### R7. Keeping and forgetting - Events are kept for 30 days and then deleted, bodies and all. Accept when: a clean-up run deletes exactly the events that are old enough. ### R8. Dashboard Only if `dashboard` is on. - A list of events: source, type, when, state and attempts, newest first, with a filter for each source and each state. - One event's page shows its headers, its body and each failure. - "Process again" runs the handler once more, whatever the state. - Only administrators reach it. Bodies can hold personal data. Accept when: "Process again" on a failed event runs its handler, and a person who is not an administrator gets 403. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests set the clock and use no outside network. - No log line holds a secret or a whole signature. - A README explains how to add a source and a handler, how to change a secret without losing events, and how to run the tests.
- Sending webhooks.
-
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_inboxid,source,event_id,event_type,headers(JSON),body(the raw bytes),state,attempts,next_attempt_at,last_error,received_at,handled_at; unique onsourceandevent_idstateis one ofwaiting,processing,done,ignoredandfailed.Signature schemes
Scheme The header holds The signature is timedt=TIME,v1=HEX, with one or morev1=partsHMAC-SHA-256, keyed with the secret, over TIME, a full stop and the body, in hexadecimalplainsha256=HEXHMAC-SHA-256, keyed with the secret, over the body, in hexadecimal TIMEis seconds since 1970. With severalv1=parts, any one that matches passes.plainsigns no time, so R2's time rule does not apply to it.Test vectors
Both use the secret
test-secret-do-not-useas ASCII text and this body:{"id":"evt_1","type":"invoice.paid","created":1700000000,"data":{"invoice":"inv_42"}}Scheme Header value timed, at time1700000000t=1700000000,v1=67792ab0d3124c0722bce4f5970dcb6cc6fe52166f53af158e5146c26904dd8fplainsha256=3e93cd005178b0844d73fac20371958a06584d8dcc5ac27ac6bfb8f57c189839For the
timedvector to pass R2's time rule, the test sets the clock to1700000000.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
waitingwithnext_attempt_atpassed, one worker per row. In Postgres claim withFOR UPDATE SKIP LOCKED; in SQLite with a singleUPDATEthat setsprocessingwhere the state iswaiting. - A row left in
processingfor 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_URLConnection string for the chosen database. WEBHOOK_SECRET_EXAMPLEThe 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-webhooksdoes, in the headerX-Webhook-Signature. - Each failure is a row in
webhook_failures: the event, the time, and the first 2,000 characters of the error.claimed_aton the inbox row says when processing began. - A request exactly
tolerance_secondsfrom 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.
# 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. -
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 table in
design.mdand a clock that tests can set. Check: migrations run from empty. - Signatures (R2). Two pure functions, one per scheme, using the
tolerance_secondsinput. Check: a test passes both vectors indesign.mdand the R2 cases. - Sources and the address (R1, R3). With the body kept as raw bytes. Check: the R1 and R3 acceptance tests pass.
- Once (R4). Check: the R4 test with 5 requests at once passes.
- Handlers and the worker (R5, R6). Check: the R5 and R6 acceptance tests pass.
- Clean-up (R7). Check: the R7 acceptance test passes.
- Dashboard (R8). Only if
dashboardis on. Check: the R8 acceptance tests pass. - 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 table in `design.md` and a clock that tests can set. Check: migrations run from empty. 2. **Signatures (R2).** Two pure functions, one per scheme, using the `tolerance_seconds` input. Check: a test passes both vectors in `design.md` and the R2 cases. 3. **Sources and the address (R1, R3).** With the body kept as raw bytes. Check: the R1 and R3 acceptance tests pass. 4. **Once (R4).** Check: the R4 test with 5 requests at once passes. 5. **Handlers and the worker (R5, R6).** Check: the R5 and R6 acceptance tests pass. 6. **Clean-up (R7).** Check: the R7 acceptance test passes. 7. **Dashboard (R8).** Only if `dashboard` is on. Check: the R8 acceptance tests pass. 8. **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 table in
Is it for me?
- Kind
- app part
- Platforms
- backend, web
What does it need?
- Agent permissions
- shell, network
- Secrets it reads
DATABASE_URLWEBHOOK_SECRET_EXAMPLE
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/incoming-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.