10 min read
|
Published
|
Updated

Webhook Signature Verification with Personal Secrets

Set a personal secret and Chaingateway signs every webhook with an X-Signature header. How the HMAC works, a Node.js check, and what it does not cover.

Chapters
C
Chaingateway Team
Blockchain Experts

Reviewed by Maurice Sobiera

A personal secret is a key that you set in your Chaingateway profile. Once it exists, every outgoing webhook carries an X-Signature header: an HMAC-SHA256 of the transaction ID, signed with that secret and Base64-encoded. Your server recomputes the value and compares it, which shows that the request came from Chaingateway.

Why do webhooks need a signature?

A webhook endpoint is a public URL, and anyone who knows it can send a request to it. Without a check, a forged “payment received” request could release goods or credit an account. A shared secret fixes this. Only Chaingateway and your server know the key, so only they can produce a matching signature. The construction is HMAC, defined in RFC 2104: a hash function combined with a secret key.

How do you set a personal secret?

Open your profile settings in the dashboard, find the webhook personal secret card and click “Set Personal Secret”. To replace an existing secret, click “Regenerate Secret”. Two details from the documentation matter:

  • Setting a secret for the first time enables the X-Signature header on all outgoing webhooks. Make sure your server accepts the new header and verifies it before you rely on it.
  • A regenerated secret takes effect immediately. Update your handler before you click, or at the same time, otherwise valid notifications fail verification.

How is the signature built?

The documented procedure has three steps. Read the txid field from the webhook payload. Compute HMAC-SHA256 with your personal secret as the key and the txid string as the message. Encode the result as Base64 and compare it with the header. A payload looks like this (from the webhook guide):

{
"id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed",
"webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8",
"from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN",
"to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM",
"blocknumber": "65542464",
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988",
"amount": 108935
}

How do you verify the signature on your server?

Recompute the HMAC from the txid and compare it to the header in constant time. The following Express handler does that. It reads the secret from an environment variable, rejects a missing or wrongly sized header, and answers with 200 only for valid requests:

const crypto = require('crypto');
const express = require('express');
const app = express();
app.use(express.json());
function isValid(txid, received, secret) {
const expected = crypto.createHmac('sha256', secret).update(txid).digest('base64');
const a = Buffer.from(expected);
const b = Buffer.from(received || '');
// timingSafeEqual throws when lengths differ, so check first
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/hooks/deposit', (req, res) => {
const ok = isValid(req.body.txid, req.get('X-Signature'), process.env.CG_PERSONAL_SECRET);
if (!ok) return res.sendStatus(401);
// process req.body.txid, deduplicate on it, then acknowledge
res.sendStatus(200);
});
app.listen(3000);

The documentation also has Python, Java and PHP versions. In Python, use hmac.compare_digest for the comparison. In Node.js, crypto.timingSafeEqual does the same job. A plain == comparison can leak timing information.

How can you test the handler?

Compute a signature yourself and send a fake notification to your local server. The openssl command below produces the same Base64 HMAC that the handler expects. Use a test secret, never your real one:

Terminal window
TXID=18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988
SIG=$(printf '%s' "$TXID" | openssl dgst -sha256 -hmac "test-secret" -binary | base64)
curl -i -X POST http://localhost:3000/hooks/deposit \
-H "Content-Type: application/json" \
-H "X-Signature: $SIG" \
-d "{\"txid\": \"$TXID\"}"

Start the server with CG_PERSONAL_SECRET=test-secret. The request returns 200. Change one character of the secret or of the signature, and it returns 401. Run this test again after each deployment of the handler, and again after you regenerate your real secret.

What does the signature not cover?

It covers the transaction ID and nothing else. Per the documented construction, only txid goes into the HMAC. Two consequences follow:

  • A valid signature proves that Chaingateway sent a notification for that transaction. It does not prove that amount, to or contractaddress in the body are unchanged. If those fields decide a payout, check them against the chain or against the expected values for the order.
  • The same transaction can arrive more than once, for example after you ask for a failed notification to be sent again, and each copy has the same valid signature. Deduplicate on txid.

Webhooks are not retried automatically. Failed notifications are listed per chain, and you request a resend for each. Solana has no webhooks. Where webhooks exist, signing works the same way on every chain.

How do you rotate the secret without dropping notifications?

A regenerated secret takes effect immediately, so the order of steps matters. Make the handler accept two secrets for a short period, then regenerate:

  1. Deploy a handler version that tries the current secret first and a second, optional CG_PERSONAL_SECRET_NEXT if the first check fails.
  2. Regenerate the secret in your profile and copy the new value.
  3. Put the new value into CG_PERSONAL_SECRET_NEXT and redeploy.
  4. Send a test transfer on the testnet and confirm that the handler accepts it.
  5. After a day, promote the new secret to CG_PERSONAL_SECRET and remove the old one.

The documentation does not say which secret signs a notification that you resend after a rotation. Keep the two-secret window open until the failed-notification list is empty.

What happens if you have not set a secret?

Webhooks are then sent without the X-Signature header. Your handler must not treat a missing header as valid. Decide per environment: in production, reject requests without a signature once you have set a secret, and in a local test environment you may allow them. The header is also the way to find out whether a secret is active: a notification without it means no secret is set on your account.

Where is the full reference?

The webhook security guide lists the steps and the code in four languages, and the webhook guide explains how to create webhooks and receivers.

How we write these articles

Ready to build this yourself? Get your API key — 7-day trial, no card required — or see the Blockchain API for the full endpoint reference.

C
Chaingateway Team
Blockchain Experts

The Chaingateway team is dedicated to simplifying blockchain integration for developers worldwide.