Webhook Consumers

Webhook handlers must be replay-safe and verifiable.

Verification

• Validate provider signatures before parsing payloads.
• Reject requests that fail signature checks with 401.
• Store the raw body if the provider requires exact-byte verification.

Dedupe

• Persist event IDs.
• Skip already processed IDs.
• Make handlers idempotent even if dedupe storage is delayed.

Processing model

1. Verify signature.
2. Validate payload schema.
3. Persist event record.
4. Apply domain state update.
5. Return success quickly.

Keep heavy side effects in async workers if possible.

Failure handling

• Return non-2xx only for transient retryable failures.
• Alert on repeated processing failures.
• Keep dead-letter workflow for poison events.

Example use cases in Mimic

• Stripe subscription and invoice updates
• Agent/job status callbacks
• External event feeds that enrich pilot analytics