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?

Outgoing webhooks: deskOutgoing webhooks: endpointOutgoing webhooks: deliveryOutgoing webhooks: sign in

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.

    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

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

    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_endpointsid, owner_id, url, event_types (empty means all), secret_encrypted, old_secret_encrypted, old_secret_until, enabled, disabled_reason, created_at
    webhook_eventsid, owner_id, type, data, created_at
    webhook_deliveriesid, event_id, endpoint_id, state, attempts, next_attempt_at, created_at
    webhook_attemptsid, delivery_id, status, duration_ms, response_start, error, at

    state is one of waiting, sending, delivered and failed.

    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

    PartValue
    Secret, as ASCII texttest-secret-do-not-use
    Time1700000000
    Body{"id":"evt_1","type":"invoice.paid","created":1700000000,"data":{"invoice":"inv_42"}}
    Signed text1700000000. followed by the body
    Header valuet=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

    SecretPurpose
    DATABASE_URLConnection string for the chosen database.
    WEBHOOK_ENCRYPTION_KEYEncrypts signing secrets. 32 random bytes, base64.
    WEBHOOK_ALLOW_LOCALSet 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.

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

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

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