Verifying Webhook Signatures
Every webhook is signed so you can check that Minteo sent it and that nobody changed it on the way. You must verify the signature before you act on a webhook.
signature.checksum? Move to X-Minteo-SignatureThe signature.checksum field (and its X-Hook-Checksum header) is deprecated. It signs only a few fields, and the list of those fields travels in the same message. A receiver that reads signature.properties from the message can be fed a forged webhook that passes the check.
- Today, if you still verify
signature.checksum: stop readingsignature.propertiesfrom the message and use the fixed lists in Legacy checksum. - Then: verify
X-Minteo-Signatureas described below. See Migrating from the legacy checksum.
Security considerations
Your webhook secret is different from your API key.
- The secret is used only for webhook signature verification
- Store the secret securely (environment variables, secret manager)
- Never commit the secret to version control
- Never expose the secret in client-side code
- Rotate the secret if the secret is compromised
Minteo stores your secret encrypted in our database and only decrypts it when needed.
Getting your secret
You can view your current webhook secret at any time in the Board:
- Production
- Sandbox
How the signature works
Every delivery attempt carries an X-Minteo-Signature header:
X-Minteo-Signature: t=1763560000,v1=c7d4cce0739936c4214b5eda26b6602b27c85eae7f5940178cd8ec75ea02a013| Part | Meaning |
|---|---|
t | Unix timestamp (seconds) of this delivery attempt. Same value as the body's timestamp. |
v1 | Lowercase hex HMAC-SHA256 of t, a period (.) and the raw request body, using your webhook secret as the key. |
v1 = HMAC-SHA256(key = your secret, message = t + "." + raw body)The signature covers every byte of the body: event_type, event_id, hook_id, all of data. Changing any of them breaks it. Because t is signed too, an old webhook cannot be passed off as new.
The header is a list of key=value pairs separated by commas. Ignore keys you do not know: Minteo may add new schemes (for example v2) next to v1.
Verification process
Step 1: Read the raw body
Read the request body as raw bytes, before parsing it as JSON. If you parse it and serialize it again, spacing or key order may change and the signature will not match.
Step 2: Parse the header
Split X-Minteo-Signature by , and each part by the first =. Take t and every v1 value. Reject the request if the header is missing, t is missing, repeated or not a plain integer, or there is no v1.
Step 3: Check the timestamp
Reject the request if t is more than 300 seconds (5 minutes) away from your server's clock, in either direction. Every retry is signed again when it is sent, so a valid delivery is never older than that. Keep your server's clock synchronized (NTP).
Step 4: Compute the expected signature
Compute the HMAC-SHA256 of t + "." + rawBody with your secret, as lowercase hex. Use t exactly as it appears in the header.
HMAC accepts an empty key. If your secret fails to load (an unset environment variable), an empty secret would make forged webhooks with an empty-key signature pass. Refuse to verify, and alert, when the secret is empty.
Step 5: Compare in constant time
Compare your value with each v1 using a constant-time comparison (crypto.timingSafeEqual in Node.js, hmac.compare_digest in Python). A plain === or == leaks how many characters matched.
If no v1 matches, reject the webhook with 401.
Step 6: Then parse and deduplicate
Only now parse the body as JSON. Skip events you already processed, by event_id (see Implement idempotency).
A valid signature proves the webhook came from Minteo. Before an irreversible action, such as refunding your user because a payout was rejected, read the payout or item again from the API and act on the state the API returns.
Implementation example
import crypto from 'node:crypto';import express from 'express';
const TOLERANCE_SECONDS = 300;
/** * True when the X-Minteo-Signature header is a valid signature of rawBody * under one of the secrets, made less than TOLERANCE_SECONDS ago. */function verifyMinteoSignature(rawBody, header, secrets, nowSeconds = Math.floor(Date.now() / 1000)) { if (secrets.length === 0 || secrets.some(secret => !secret)) { throw new Error('Minteo webhook secret is not configured'); } if (!header) return false;
const pairs = header.split(',').map(part => { const index = part.indexOf('='); return [part.slice(0, index).trim(), part.slice(index + 1).trim()]; }); const timestamps = pairs.filter(([key]) => key === 't').map(([, value]) => value); const signatures = pairs.filter(([key]) => key === 'v1').map(([, value]) => value); const timestamp = timestamps[0];
if (timestamps.length !== 1 || !/^[1-9]\d*$/.test(timestamp) || signatures.length === 0) return false; if (Math.abs(nowSeconds - Number(timestamp)) > TOLERANCE_SECONDS) return false;
return secrets.some(secret => { const expected = crypto .createHmac('sha256', secret) .update(`${timestamp}.${rawBody}`) .digest();
return signatures.some(signature => { const received = Buffer.from(signature, 'hex'); return received.length === expected.length && crypto.timingSafeEqual(received, expected); }); });}
const app = express();
// Keep the raw body: the signature is over the exact bytes Minteo sent.app.post('/webhooks/minteo', express.raw({ type: 'application/json' }), (req, res) => { const rawBody = req.body.toString('utf8'); const secrets = [process.env.MINTEO_WEBHOOK_SECRET]; // add the previous one while rotating
if (!verifyMinteoSignature(rawBody, req.get('X-Minteo-Signature'), secrets)) { return res.status(401).send('Unauthorized'); }
const event = JSON.parse(rawBody); // Deduplicate by event.event_id, then process the webhook res.status(200).send('OK');});Calculation example
Given this raw body (shortened for the example):
{"event_id":"EVENT#3f6b1c2e-8d4a-4f5e-9a7b-2c1d0e9f8a7b","event_type":"payout.updated","data":{"payout":{"id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","status":"COMPLETED"}},"timestamp":1763560000}With t=1763560000 and the secret whsec_abc123xyz, the signed message is 1763560000. followed by the raw body, and:
HMAC-SHA256("whsec_abc123xyz", "1763560000.{\"event_id\":...}") = c7d4cce0739936c4214b5eda26b6602b27c85eae7f5940178cd8ec75ea02a013You can reproduce it from a terminal:
printf '%s' '1763560000.{"event_id":"EVENT#3f6b1c2e-8d4a-4f5e-9a7b-2c1d0e9f8a7b","event_type":"payout.updated","data":{"payout":{"id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","status":"COMPLETED"}},"timestamp":1763560000}' | openssl dgst -sha256 -hmac 'whsec_abc123xyz'Secret rotation
Each delivery attempt is signed with the secret that is current when the attempt is sent. When you rotate your secret in the Board, the next attempt of every event, retries included, uses the new secret. Only an attempt already on its way when you rotate carries the old one.
Recommended rotation process
To rotate your secret without downtime:
- Update your code to accept both the current and the previous secret (both visible in Board)
- Deploy the updated code
- Rotate the secret in Board
- Once your endpoint receives webhooks signed with the new secret, remove the previous one from your code
Migrating from the legacy checksum
X-Minteo-Signature is sent today on every webhook, next to the legacy signature object and X-Hook-Checksum header, which have not changed. You can switch whenever you are ready:
- Make your endpoint read the raw body (Step 1).
- Verify
X-Minteo-Signatureas described above. While you test it, you can keep checking the legacy checksum as well. - Once it works, stop checking
signature.checksumandX-Hook-Checksum.
The legacy checksum will be removed in the future. Minteo will announce the date in advance.
Legacy checksum (deprecated)
signature.properties from the messageEarlier versions of this page told you to take the list of signed properties from signature.properties. Do not do that: with one real webhook, an attacker can build another one whose signature.properties points at a field they control and whose checksum still matches. Use the fixed lists below, and move to X-Minteo-Signature.
signature.checksum is the uppercase hex SHA256 of the values of a fixed list of fields, concatenated in order, followed by the timestamp and your secret. The list depends only on the event type:
event_type | Fields, in order |
|---|---|
order.updated | order.id, order.status, order.amount |
payout.updated | payout.id, payout.status, payout.transfer_amount |
payout.item.updated | payout_item.id, payout_item.status, payout_item.effective_amount |
Because only these fields are signed, and with no separator between them, the legacy checksum does not protect event_type, event_id, the rest of data, or the age of the message. If you cannot move yet, at least:
- Reject event types not in the table, and read the entity from the key that matches the event type (
data.payout_itemforpayout.item.updated). - Check the format of the signed values before computing the checksum: the
idis a UUID, thestatusis one of the documented values, the amount is numeric. - Reject messages whose
timestampis more than 5 minutes old. - Read the entity again from the API before an irreversible action.
import crypto from 'node:crypto';
// Fixed per event type. Never read signature.properties from the message.const SIGNED_FIELDS = { 'order.updated': ['order.id', 'order.status', 'order.amount'], 'payout.updated': ['payout.id', 'payout.status', 'payout.transfer_amount'], 'payout.item.updated': ['payout_item.id', 'payout_item.status', 'payout_item.effective_amount'],};
function validateLegacyChecksum(event, secret) { const fields = SIGNED_FIELDS[event.event_type]; if (!fields) return false;
const values = fields.map(path => getNestedValue(event.data, path)).join(''); const computed = crypto .createHash('sha256') .update(`${values}${event.timestamp}${secret}`) .digest('hex') .toUpperCase();
const received = Buffer.from(String(event.signature?.checksum ?? '')); const expected = Buffer.from(computed); return received.length === expected.length && crypto.timingSafeEqual(received, expected);}
function getNestedValue(obj, path) { const value = path.split('.').reduce((acc, key) => acc?.[key], obj); return `${value ?? ''}`.trim();}