# Hook Contract

> Check a platform's outbound webhooks from the sender's side, then write the event catalog and the delivery
> contract. Paste the event names, one real delivery (headers and raw body) and the retry schedule; the browser lints
> the names (resource.action, past tense, one delimiter), reads the envelope and the signing scheme against Standard
> Webhooks, verifies the delivery's HMAC signature with a test secret that never leaves the page, works out what the
> retry schedule really does, checks dead-lettering, ordering, auto-disable and the debugging surface, and writes
> verification snippets for Node, Python and Go. Metered runs write the event catalog and envelope, and the delivery
> contract subscribers can rely on. Built on the SkillSafe skill @samber/webhook-platform-design, from
> samber/developer-platform-skills (MIT), by Samuel Berthe. It never claims exactly-once delivery.

https://hook-contract.skillsafe.ai/

## What is free
- Event names: resource.action, the action in the past tense (invoice.paid, never invoice.pay), [a-zA-Z0-9_.] only, one delimiter, every event described.
- The envelope: one string naming the event, a stable per-event ID, a timestamp in Unix seconds, a payload under about 20 kB.
- Signing: the three Standard Webhooks headers, a signed timestamp (replay protection), v1,<base64> signatures, room for two signatures during rotation, a whsec_ prefix - and a verifier: HMAC-SHA256 over id.timestamp.raw_body in your browser.
- Delivery: automatic exponential retries spanning hours to about a day (3 days at most), non-retriable 4xx dead-lettered at once, an ack timeout around 10 s, ordering stated, dead-letter retention of 7 to 30 days, auto-disable with an out-of-band notice.
- The debugging surface: delivery logs, replay, test events.
- Verification snippets (Node, Python, Go) and exports: the checks (.csv), everything (.json).

## The metered lanes
Two tasks on gpt-terra, metered per run, routed by `task`. Input string fields: `task` (catalog or contract), `platform`, `delivery`, `carry` (contract only: the catalog's event names) and `facts`. The test secret is never part of the input.
- `catalog` replies with `summary`, `convention`, `events` (name, replaces, description, payload, fields), `envelope` (placement, payload, versioning), `example` (a delivery with Standard Webhooks headers) and `caveats`.
- `contract` replies with `summary`, `build`, `guarantee`, `ordering`, `dedup`, `retry` (schedule in seconds, span), `timeout_s`, `non_retriable`, `retry_after`, `dlq`, `disable`, `lifecycle`, `portal`, `docs` and `caveats`.
The page holds every reply to its own facts: every listed event covered once with a past-tense resource.action name, an example signed the standard way; the build rung it settled, at-least-once, a schedule that grows and spans the floor, 4xx dead-lettered, the three subscription states, the five contract facts in the docs, and never exactly-once.

## Links
- API tutorial: https://hook-contract.skillsafe.ai/api.html
- Source skill: https://skillsafe.ai/skill/@samber/webhook-platform-design