Skip to content

Verify Webhook Signatures with HMAC

The X-Signature header of a Chaingateway webhook lets you check that a request really comes from Chaingateway. It contains the base64-encoded HMAC-SHA256 of the transaction id (txid) from the payload, keyed with your personal secret. Your receiver recomputes the value and compares it with the header. The header is sent once you have set a personal secret.

Signature check: Chaingateway computes HMAC-SHA256 over the txid with your personal secret and sends it in X-Signature, your receiver recomputes the value and compares it in constant time Chaingateway signs base64( HMAC-SHA256( personal_secret, txid ) ) POST to your receiver JSON body with txid, header X-Signature Receiver recomputes the HMAC same secret, same txid Constant-time comparison equal: accept, different: reject with an errorstatus
Only the txid is signed. The other payload fields are not part of the signature.

What does the X-Signature header protect against?

Section titled “What does the X-Signature header protect against?”

It protects against forged requests: anyone can send a POST request to your public receiver URL, but only a sender who knows the personal secret can produce a matching signature. HMAC, defined in RFC 2104, combines a hash function with a secret key, here SHA-256. NIST FIPS 198-1 specifies the same construction as the Keyed-Hash Message Authentication Code.

The signature covers the txid and nothing else. The amount, the addresses and the token fields in the body are not signed. A valid pair of txid and signature therefore does not prove that the rest of the body is unchanged. After the check, treat the txid as a lookup key: read the transaction with GET /api/v2/{chain}/transactions/{txid} and credit the payment from the data that the API returns, not from the amount in the notification body.

You set or regenerate the personal secret in your profile settings. Follow these steps:

  1. Open Profile Settings.
  2. Find the section labeled “Personal Secret”.
  3. If no secret is set, click “Set Personal Secret” to generate one. If a secret exists, click “Regenerate Secret” to replace it.

Two details matter for a running system. If you have no personal secret yet, adding one switches on the X-Signature header for all outgoing webhooks. Deploy a receiver that accepts and verifies the header before you do this. If you regenerate an existing secret, the new secret applies to webhook notifications immediately. Update the receiver at the same time, or it rejects valid requests.

Chaingateway reads the txid from the payload, computes an HMAC with the SHA-256 hash function over it, using the personal secret as the key, and base64-encodes the 32 result bytes. The txid is the unique transaction identifier that already appears in the webhook body, so the receiver has everything it needs to recompute the value. The secret is shared only between Chaingateway and you.

Recompute the HMAC from the txid in the body and compare it with the header value. Use a constant-time comparison function so that the comparison time reveals nothing about the expected value. The examples below do this in Python, Java, PHP and JavaScript.

import hmac
import hashlib
import base64
def verify_signature(txid, received_signature, personal_secret):
# Generate the expected signature
expected_signature = base64.b64encode(hmac.new(
personal_secret.encode(),
txid.encode(),
hashlib.sha256
).digest()).decode()
# Compare the expected signature with the received signature
return hmac.compare_digest(expected_signature, received_signature)
# Example usage
txid = 'your_txid_here'
received_signature = 'received_signature_here'
personal_secret = 'your_personal_secret_here'
if verify_signature(txid, received_signature, personal_secret):
print("Signature is valid.")
else:
print("Invalid signature.")

Test the function with a fixed input before you connect it to live traffic. The values below are a test vector that you can reproduce with any HMAC-SHA256 tool. The secret is a placeholder, not a real personal secret. If your function returns a different value for this input, the bug is in your code and not in the webhook.

personal_secret: my_personal_secret
txid: 18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988
X-Signature: t2vU2mYBCv/UvpKprNJB7qbgrCpPXKb6NWgL77xsZgQ=

Common mistakes are hashing the whole JSON body instead of the txid, using the hex digest instead of base64, and comparing with ==, which is not constant-time. Also remember that the personal secret is account-wide. A secret that you regenerate in the profile settings changes the signature of every webhook of the account at once.

What should I do when the signature does not match?

Section titled “What should I do when the signature does not match?”

Reject the request with an error status such as 401 or 403 and do not process the body. Log the txid, the received header and the source address, so that you can tell a misconfigured secret from a forged request. If the same sender produces mismatches right after you regenerated the secret, the receiver still uses the old one. A forged request that only guesses a txid cannot produce a valid signature without the secret.

Signature verification is one layer. The following measures cover the rest of the path.

  • Serve the receiver over HTTPS, so the payload is encrypted in transit. OWASP’s REST Security Cheat Sheet recommends HTTPS for every endpoint that handles sensitive data.
  • Reject requests with a missing or wrong X-Signature with an error status, and log them.
  • Use the txid as an idempotency key. A notification that you re-send with POST /api/v2/{chain}/webhooks/notifications/{id}/retry carries the same txid and must not credit a payment twice.
  • Keep the personal secret in a secrets store, never in the repository, and rotate it if it may have leaked. Chaingateway does not retry failed deliveries on its own, so plan the update of the receiver and the secret as one step, and re-send missed notifications from the failed list afterwards.