Webhook verification practices

Events GET list/retrieve are merchant-public contracted-test. Unsupported Events methods remain unsupported. WebhookEndpoints and top-level PaymentMethods remain unavailable; this is not an endpoint-registration guide.

Verify raw bytes

Verify the exact request bytes before parsing or re-serializing JSON. Use a constant-time comparison, enforce the timestamp tolerance, and load the secret from a secret manager rather than source code.

Return 2xx quickly

When integrating with any at-least-once webhook provider, acknowledge a valid request quickly and enqueue slow work. Do not tie request acknowledgement to a long-running business transaction.

Make handlers idempotent

Deduplicate on the provider’s stable event identifier before applying a side effect. A retry must not create a second refund, fulfillment, or ledger action.

Test locally

Fluveo SDK signature helpers can verify locally constructed fixtures. That proves only the verifier; it does not prove that Fluveo issued a public endpoint secret or delivered an Event.

See Webhooks for the current quarantine and promotion boundary.