A webhook should change an order only after your server verifies its signature and matches the signed payment to a saved invoice. Coinvay signs the timestamp and exact raw request body using the merchant webhook secret.
Verify before parsing or acting
Read X-Gateway-Timestamp and X-Gateway-Signature, preserve the raw body bytes, and calculate HMAC-SHA256 over timestamp, a period, and that body. Compare the expected lowercase hexadecimal signature using a timing-safe comparison. Parsing JSON and serializing it again can change whitespace or key order, producing different bytes. The downloadable verifier in Coinvay documentation demonstrates the protocol; your application still supplies its own durable transaction.
Check meaning as well as authenticity
A valid signature says the message was authenticated; it does not prove that your application mapped it to the right purchase. Validate the event type, merchant context, signed payment ID, invoice ID, expected order, USD amount and currency. Reject stale timestamps according to your chosen freshness policy and synchronized server clock. The delivery-ID header is useful for diagnostics but is not included in the signature, so it must not be the only deduplication key.
Acknowledge durable acceptance
For an order SOFTWARE-81, atomically store the signed payment identity and enqueue one license-delivery job. Return a successful response promptly, within the gateway delivery timeout, then let a worker issue the license. A retry should find the existing payment and safely acknowledge it. Configure the public HTTPS endpoint only on a webhook-enabled plan. Sandbox webhooks use a separate endpoint and secret, carry livemode false, and are sent manually from the sandbox history.
Practical checklist
- Keep the raw request body unchanged until signature verification finishes.
- Enforce timestamp freshness and durable deduplication of the signed payment identity.
- Test an altered body, stale timestamp, wrong secret and repeated valid message.
Common questions
Can I trust only X-Gateway-Event-Id?+
No. That delivery header is not signed. Deduplicate the signed payload payment ID together with the saved invoice and order identity.
Are sandbox and live signatures interchangeable?+
They use the same signing pattern but separate secrets and endpoints. Keep test messages out of live fulfillment and verify the signed environment fields.
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.