Webhook Verification

Overview

Verification has more than one layer

Verifying a payment webhook starts with checking whether the request is authentic. But authenticity is not the whole question. A provider could legitimately send a notification for an invoice that belongs to another environment or merchant account, for a status that does not authorize fulfillment, or for an event your application already processed. A correct handler therefore checks the cryptographic signature, the expected event structure, the merchant's own order reference and the permitted status transition. These checks answer different questions and should not be collapsed into one “verified” boolean.

How the underlying system works

Verification should begin with the unmodified HTTP request body and the provider's documented signing rules. In OxaPay's published webhook specification, payment callbacks use a merchant API key and payout callbacks use a payout API key to compute an HMAC-SHA512 signature carried in the HMAC header. Reject malformed or incorrectly signed messages before they touch payment or order state.

After authentication, inspect event type, track reference, asset, network, amount and status. Map the event to a known payment request; never trust a customer-supplied order identifier by itself. Record a deduplication key and use idempotent updates because retries are expected in distributed systems. For high-impact actions, an independent inquiry to the provider's payment-information endpoint can resolve uncertainty. Protect keys, handle rotation and record sanitized audit evidence without logging secrets.

A practical checklist in action

Suppose an endpoint receives an event claiming order 501 is paid. First compute and verify the HMAC over the untouched body, using the correct credential. Then parse the payload and check the event type and track ID. Look up the track ID in your own database and ensure it maps to order 501. Check amount, currency and relevant provider status according to your documented rules; use the payment information endpoint if the event is surprising or incomplete. Finally, apply an idempotent update—meaning that processing the same event twice yields one fulfillment decision. Return the provider-required acknowledgement without silently treating a processing failure as success.

What verification does not do

Signature verification does not itself verify a blockchain transaction's finality. A valid “confirming” event is still not “paid” simply because its HMAC matches. Conversely, querying a blockchain explorer without authenticating the provider callback does not establish which customer order should be credited. Log verification failures safely, without revealing secrets or full sensitive payloads. Make error handling explicit: rejected signatures should not change orders, and temporary internal failures should remain retriable under a tested delivery policy.

Further reading and related concepts

Reference documents: OxaPay — Webhook, OxaPay — Payment Information.

Related glossary topics: Webhook, Webhook Signature, Webhook Retry.