Issue 26 · 30 Sep 2026 · Advanced · Free
Webhook Contract Writer
A sample payload arrived in a ticket, and the integration is a handler that trusts whatever POST shows up next.
Paste a sample webhook body. Get required fields, the idempotency key, retry behavior, and how you will verify the signature.
- Category
- Automation
- Runs in
- Claude
- ChatGPT
- Cursor
What you put in and what you get out
You put in
Paste one real sample. Use a payload from the vendor's docs or a redacted delivery. Include the headers they document and what they said about retries. Remove any secret.
Agent
Webhook Contract Writer
You get out
The check. Compute HMAC-SHA256 over the raw body with the stored secret and compare to X-Signature. Mismatch is 401 and no side effect. No bypass is described.
Sample you can paste
Sample POST body from the form vendor, sent to us:
{
"id": "evt_1844",
"type": "refund.requested",
"created": "2026-09-30T10:00:00Z",
"data": { "order_id": "1844", "amount": 40, "currency": "eur" }
}
Headers they document: X-Signature is hex HMAC-SHA256 of the raw body using a signing secret we store. They retry for 24 hours on non-2xx. The id is stable across retries.
We must not treat a second delivery as a second refund.
Do not write a bypass. Write the check we should perform.Share this agent
Webhook Contract Writer — You put in Sample POST body from the form vendor, sent to us:. You get out The check. Free from One Agent a Day.
30-second demo
0:00
The sample
evt_1844, type refund.requested, order 1844, amount 40. Signature header documented as HMAC-SHA256 of the raw body. Retries for 24 hours.
How it works
A sample payload is not a contract until you decide which fields are required, which field makes a retry harmless, and how you know the body came from the vendor. You paste the sample and the vendor's own words about signatures and retries.
The signature section is a check you perform: compute the MAC over the raw body with the secret stored in your tool, compare it to the header, and stop if it does not match. It is not a guide to forging a header. The idempotency key is the id the vendor said is stable. A duplicate returns success and does not repeat the side effect.
Write the handler in that order. If the vendor's docs disagree with the sample, the contract names the disagreement instead of guessing.
Use it
Step 1
Paste one real sample
Use a payload from the vendor's docs or a redacted delivery. Include the headers they document and what they said about retries. Remove any secret.
Step 2
Say what a duplicate must not do
If a retry must not create a second refund, write that down. The contract's idempotency section depends on it.
Step 3
Paste the prompt
You get required fields, the key you will store, the signature check in defensive terms, and the response code for a duplicate.
Step 4
Implement the check before the side effect
Verify the signature on the raw body, then look up the event id, then do the work. The agent describes that order. It does not give you a way to forge a signature.
Prompt
webhook-contract-writer.prompt.txt
You write a webhook contract from a sample payload and the vendor notes the human pasted. You describe how to verify a signature. You do not describe how to forge one.
INPUTS
- Sample body.
- Documented headers and retry behavior.
- The side effect a duplicate must not repeat.
RULES
- Required fields are the ones the side effect needs. Mark the rest optional.
- The idempotency key is a field they said is stable across retries. If they did not, ask and stop.
- Signature: say which header, which algorithm they named, and that the MAC is over the raw body using a secret stored on our side. Compare in constant time if you mention comparison. A mismatch means no side effect.
- Do not provide a bypass, a test secret from a real vendor, or steps to craft a valid signature for someone else's endpoint.
- Retry behavior is quoted from their notes. If missing, write "not in the notes."
- Response codes: 2xx only after the event id is stored or recognized. 401 on a bad signature. Say what a duplicate returns.
OUTPUT
## Required
## Optional
## Idempotency
Key, and what a duplicate returns.
## Verify
The check, in order, before the side effect.
## Retries
From their notes, or "not in the notes."
## Out of scope
Forging, bypassing, and anything you refused.Config
webhook-contract.defaults.json
{
"version": 1,
"verifyBeforeSideEffect": true,
"duplicateRepeatsSideEffect": false,
"forgeSignature": false
}
Related agents
Tomorrow's drop
Get the next agent in your inbox
One email when the drop goes up. No digest, no course. Unsubscribe whenever the provider lets you.
Pro and custom
€9/month when Pro opens
Early look at the next drop, a better archive, and the occasional agent that does not fit the public mix. The daily agent stays free. A custom build is €49–199. Nothing is charged from this form.
Join the Pro waitlist