Form webhook checklist: reliable delivery, retries and replay safety

Stable definition

A webhook is an HTTP event delivery from one system to a configured endpoint. It is not a synchronized database transaction. The sender may retry, events may arrive out of order and the receiver may accept the request before downstream CRM, routing or email work completes.

This checklist separates transport receipt from business processing, then tests the failure states between them. It applies to form platforms that send webhooks directly and to integration layers that translate a form submission into an HTTP event.

Twelve-field event envelope

Do not put secrets in the payload. Treat the body as untrusted input even after transport authentication. A W3C Trace Context trace-id is for correlating work across systems; it is not a substitute for the sender's unique event ID or the receiver's idempotency key.

Receipt and processing are different states

The receiver should capture the exact raw body needed for signature verification, validate the signature and timestamp, check the event ID, persist a minimal durable receipt and return the documented success response quickly. Expensive CRM lookups, enrichment, email generation and file processing belong in a retryable worker or queue.

A transport dashboard showing HTTP 200 does not prove that an owner was assigned, a contact was updated or a follow-up message was sent. Each required action needs its own recorded outcome.

Retry and ordering contract

As checked September 25, 2026, Stripe's current webhook documentation says live-mode events can be retried for up to three days with exponential backoff. It also says delivery order is not guaranteed, duplicate deliveries can occur and event IDs should be logged to prevent repeated processing. Those are Stripe's documented behaviors, not a universal timing standard; use the general reliability model with the chosen sender's current contract.

Apply a uniqueness constraint to the event ID and destination. Then make every business action idempotent with a separate key such as evt_9001:crm_update. Event deduplication prevents the same delivery from entering the pipeline twice; action idempotency prevents a partially completed replay from repeating the actions that already succeeded.

When the source contract supports retrieval, fetch the missing current object rather than inferring state from arrival order. Preserve both occurred_at and delivered_at; neither alone proves that an earlier event has been processed.

Signature and input checks

Stripe's signature guidance requires the exact raw request body, the signature header and the endpoint secret for verification. Whatever sender is selected, follow its current signing specification before parsing or mutating state. Do not apply one provider's header format or timestamp tolerance to another provider.

1. Read the exact raw body within a documented size limit.
2. Verify the signature, timestamp and expected endpoint secret before mutable work.
3. Allowlist content types, event types and schema versions.
4. Parse into bounded fields and reject unexpected shapes safely.
5. Rotate signing secrets with a tested overlap and rollback plan.
6. Log safe identifiers and error classes, never secrets or full sensitive payloads.

If distributed tracing is used, follow the W3C Trace Context privacy and security considerations. Trace values can correlate activity across services, so access and retention need the same deliberate controls as other operational metadata.

Failure ownership

Every terminal failure record needs the event ID, event type, first and latest attempt, failed action, error class, safe context, owner and next recovery step. A dead-letter destination is useful only when someone monitors it and can replay safely.

Retention should be long enough for operational recovery but limited to the documented purpose. Where replay could send email, change ownership or create billing consequences, require an action preview or explicit approval appropriate to the risk.

Worked replay-safe example

A form platform sends submission.accepted for submission sub_205. The endpoint verifies the signature, stores receipt evt_9001 and returns the documented success response. A worker updates the contact and assigns the qualification queue using action keys derived from evt_9001.

The sender retries after a timeout. The receiver finds the durable receipt and does not enqueue a second copy. Later, a replay occurs after the contact update succeeded but before the queue assignment completed. The worker reads the action ledger, skips evt_9001:crm_update and safely retries only evt_9001:queue_assignment.

A status event then arrives before an earlier enrichment event. The handler uses the event type and current source state instead of arrival order. This preserves the accepted form event while preventing a late, stale delivery from overwriting the newer contact state.

Eight-case replay proof test

Run with synthetic records in the intended sender account, endpoint and downstream workspace. Record the expected transport state, business state and observable evidence for each case.

1. Valid signed event: one durable receipt and one set of required actions complete.
2. Invalid signature: the request is rejected and changes no business state.
3. Stale signature timestamp: the documented tolerance is enforced without parsing into mutable work.
4. Same event ID twice: the second delivery repeats no side effect.
5. Same submission with a new legitimate event: the new event is retained and handled according to type.
6. Events out of order: the final state remains correct without relying on arrival sequence.
7. Worker failure after durable receipt: transport stays accepted while processing becomes visibly retryable.
8. Downstream timeout and replay: completed actions are skipped and incomplete actions resume safely.

Evidence and limitations