Skip to content

[docs] Document webhook delivery guarantees (semantics + ordering + dedup window) #62

@B2JK-Industry

Description

@B2JK-Industry

Friction

For a webhook to be useful in a distributed-systems sense, the destination needs to know the delivery guarantee. Today KH's docs are silent on:

  • Is webhook submit at-most-once? at-least-once? exactly-once?
  • If at-least-once, what's the dedup window? (Issue [docs] Document Idempotency-Key / retry semantics on workflow webhook submissions #51 covers Idempotency-Key, which would be the mechanism, but there's no documented behavior even if the header were honored)
  • Are submissions ordered? (Across workflow, within workflow, within session?)
  • What happens to in-flight submissions during a KH platform deploy? Drained? Rejected? Held?

Adapter callers building idempotent / queue-backed integrations need to know these to design correctly. SBO3L's executor_callback pipeline currently assumes at-least-once with operator-managed dedup — a guess based on most webhook platforms.

Proposed fix

Publish a one-page docs/delivery-guarantees.md (or section in the workflow webhook reference) that answers, for the webhook surface:

Question Answer
Delivery semantics at-least-once / at-most-once / exactly-once
Ordering per-workflow / global / none
Dedup window (assuming #51 lands)
Deploy behavior drained / rejected / queued
Max retries (if any) N + backoff schedule

Not a code change — pure documentation. But it unblocks every adapter that wants to be production-grade.

Context

Filed as part of SBO3L's KeeperHub Builder Feedback round 3 for ETHGlobal Open Agents 2026. Foundational to #51 (Idempotency-Key) + #52 (retry semantics) — together: the reliability contract.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions