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?

Incoming webhooks: homeIncoming webhooks: inboxIncoming webhooks: eventIncoming webhooks: login

What can I customize?

Database

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.md Requirements 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.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.
    # 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.
    

    Open spec.md as plain text

  • design.md Data 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 database input.

    TableColumns
    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 on source and event_id

    state is one of waiting, processing, done, ignored and failed.

    Signature schemes

    SchemeThe header holdsThe signature is
    timedt=TIME,v1=HEX, with one or more v1= partsHMAC-SHA-256, keyed with the secret, over TIME, a full stop and the body, in hexadecimal
    plainsha256=HEXHMAC-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"}}
    SchemeHeader value
    timed, at time 1700000000t=1700000000,v1=67792ab0d3124c0722bce4f5970dcb6cc6fe52166f53af158e5146c26904dd8f
    plainsha256=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

    SecretPurpose
    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-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.

    # 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.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    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.
    # 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.
    

    Open tasks.md as plain text

Is it for me?

Platforms
backend, web

What does it need?

Agent permissions
shell, network
Secrets it reads
DATABASE_URL WEBHOOK_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.