Webhook Signature
Pronunciation: WEB-hook SIG-nuh-cher
Definition
A webhook signature is a cryptographic authentication value sent with a callback so the receiver can test whether covered bytes were produced with trusted key material. For OxaPay merchant and payout webhooks, its documentation specifies an HMAC-SHA512 value in the HMAC HTTP header, calculated over the raw request body using the corresponding API key.
Overview
What a cryptographic signature tells you
A webhook signature is like a tamper-evident seal on a delivery note. The provider computes a short cryptographic value using the message contents and a shared secret. Your server computes the same value using the message it received. If they match under the expected algorithm and key, the body was very likely produced by someone who knows that secret and was not changed in transit. In this context, “signature” may mean an HMAC, not the public/private-key digital signatures used to authorize blockchain spending.
How the underlying system works
Signatures help detect forged or modified callbacks, but correct verification depends on using the exact input bytes and key documented by the provider. Serializing parsed JSON again can change whitespace, ordering or encoding and invalidate a legitimate signature. Compare the calculated and received digests with a constant-time comparison function to avoid avoidable timing leakage.
An HMAC alone does not prove freshness. A previously valid signed body may be replayed unless the application deduplicates events and checks any available replay controls. Protect webhook keys in server-side secret storage, apply key rotation procedures and keep payment and payout credentials separate. Do not place secret keys in browser code or logs.
Why the exact bytes matter
Imagine a JSON callback arrives with spaces, line breaks and fields in a particular order. If your application parses it into an object and serializes it again, those bytes may change even though the JSON means the same thing. A raw-body HMAC check would then fail. The safer procedure is to read the original bytes once, compute the expected HMAC with the configured provider key and compare the result to the received header using a constant-time comparison routine. In OxaPay's documented payment webhook flow, the calculation uses HMAC-SHA512 and the merchant API key; payout callbacks use the corresponding payout key.
An authentic message can still be repeated
A valid signature does not mean the event is new, the invoice is settled, or fulfillment should occur immediately. A previously valid callback might be replayed, either intentionally or because of normal retries. Store a deduplication identity appropriate to the payload, check the existing invoice state and use a provider status query when necessary. Protect signing keys in server-side secrets management; never put them in checkout JavaScript or a public repository. If a key leaks, someone who knows it may be able to forge convincing notifications, so rotation and incident response matter.
Further reading and related concepts
Reference documents: OxaPay — Webhook.
Related glossary topics: Webhook, Webhook Verification, API Key.
Example
Your callback receives a JSON body and an HMAC header. The server computes HMAC-SHA512 from the unmodified request body and the appropriate secret, compares values safely, then records the verified event before updating the corresponding invoice.
Comparison
A signature is data attached to the callback; webhook verification is the receiver's procedure for checking it and applying replay and business rules.
Key Takeaway
Verify the HMAC over raw bytes with the correct key; authenticity does not replace idempotency or state validation.
Sources
- NIST Documentation: Cryptographic Standards And Guidelines — NIST (2026-07-30)
- OxaPay Documentation: Webhook — OxaPay (2026-07-30)
- Stripe Documentation: Webhooks — Stripe (2026-07-30)