Webhook contract before the first send

A prepaid send without a webhook contract is spend with no shared truth. Buyers must lock the signed URL, the event list, and the idempotency key before the first paid message leaves the wallet — not after finance asks why status and ledger disagree. This page is that buyer path, not a keys-at-launch checklist and not a signature deep-dive.

Related: webhooks and keys at launch, webhooks that survive launch, Prepaid hold before first debit, Day-1 runway: what must be green.

IOSOR is white-label prepaid. USD 20 funds a contract pilot on one corridor; soft review near USD 1,000/month prices “send first, contract later” as recon debt. Clients see white-label event names only.

Agree the contract before the first paid send

Paid send means the wallet can debit. Contract means product, finance, and ops already share where callbacks land, which events count as money or status truth, and which key makes retries safe. Launch habits and runway can look green while the contract is still a Slack thread — that is not ready. See webhooks and keys at launch and Day-1 runway: what must be green. Do not buy traffic on last week’s staging callback URL.

Signed URL and consumer ownership

A signed URL without an owner becomes folklore at 02:00. Soft USD 1,000/month treats folklore as volume risk; USD 20 proves one URL, one owner, one smoke with 2xx only after signature middleware is on. See also webhooks that survive launch.

Event types product and finance share

List events that may move money or status before the first send: accepted, delivered, failed, expired, inbound STOP, and any verify result you treat as truth. Unlisted events fail closed — they do not invent ledger rows. Shared words: Shared status language for product and finance. Hold still fails closed without prepaid proof — Prepaid hold before first debit. The contract is the event menu; later gates decide whether each row is trusted.

Idempotency key before spend

Agree the key shape before spend: platform event or message ID, stored before side effects, readable next to the debit row. Inventing a key from timestamp plus body is how retries double-charge. Soft volume language stays blocked until a duplicate-event smoke shows one ledger line.

Buyer checklist for the webhook contract

1. Signed production URL named and owned before first paid send?
2. Event list product and finance share written — not oral?

Start with IOSOR

Enter the IOSOR console and register your signed HTTPS callback URL alongside your designated idempotency key field before enabling paid message dispatches. Ensure product, finance, and engineering team leads review the shared event schema—such as delivered, failed, and expired—to confirm unlisted callbacks automatically fail closed. Run a zero-spend duplicate-event payload test through your webhook gate to verify that retries record against a single ledger row before releasing traffic holds.

IOSOR takeaway

A webhook contract is not an informal alignment; it is an explicit boundary that protects finance and product from double-debits and phantom status updates. Establishing signing secret ownership, exact URL ownership, and strict idempotency key parsing prior to the first paid delivery prevents retry storms from inventing ledger entries.

Do freeze your callback event list and enforce an ACK-before-side-effects architecture across all inbound callbacks. Don't launch live production traffic using synthetic keys derived from timestamps or body hashes, and never rely on oral agreements for event status definitions.