A correctly signed payment webhook can still be delivered more than once. Replay protection combines timestamp freshness, durable deduplication of the signed payment identity and idempotent fulfillment in the merchant’s own application.
Do not confuse authentication with uniqueness
Signature verification establishes that a message’s signed bytes match the secret. It does not make the business action unique. A legitimate retry can carry the same payment after your endpoint timed out, and an intercepted message might be replayed. Validate the timestamp against a defined freshness window, use a synchronized server clock and reject invalid signatures before parsing payment instructions. Do not relax those checks merely to make a failing integration appear to work.
Deduplicate the signed identity
Coinvay’s delivery-ID header is not included in the HMAC. Therefore, use the signed payload payment ID, invoice and saved order context for duplicate control. For example, put a unique constraint on the accepted payment identity and create the order’s fulfillment job in the same database transaction. If a duplicate valid notification arrives, the transaction should find the existing acceptance rather than issue another license or credit.
Handle retries and secret changes deliberately
Your endpoint should acknowledge a durably accepted event quickly, then let a worker perform slower delivery. If the worker crashes, retry its job independently of webhook acceptance. Coordinate signing-secret rotation because queued delivery retries use the current secret. Sandbox uses its own secret and environment fields; accepting a test event into a live fulfillment queue is a separate isolation error. Test fresh duplicates, stale signed bodies, altered timestamps, header changes and simultaneous polling so replay protection is measured by the resulting business action.
Practical checklist
- Verify signature and timestamp freshness before acting on the payload.
- Use database uniqueness for signed payment and order identities, not only delivery headers.
- Make downstream fulfillment retries safe after both application and network failures.
Common questions
Should a repeated valid event always be rejected?+
A recognized event that was already durably accepted can normally be acknowledged without repeating fulfillment. Keep it separate from invalid or inconsistent evidence.
Can I deduplicate only by the request header?+
No. The delivery-ID header is not signed. Anchor replay handling in the authenticated payload and the invoice/order relationship.
Sources and further reading
Primary references and Coinvay product documentation. Check the linked pages for current details.
AI-assisted drafting, published by Coinvay. Examples are illustrative. Read our editorial approach.