Saltar al contenido principal

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.

Using signature.checksum? Move to X-Minteo-Signature

The 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.

Security considerations​

Critical

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:

How the signature works​

Every delivery attempt carries an X-Minteo-Signature header:

X-Minteo-Signature: t=1763560000,v1=c7d4cce0739936c4214b5eda26b6602b27c85eae7f5940178cd8ec75ea02a013
PartMeaning
tUnix timestamp (seconds) of this delivery attempt. Same value as the body's timestamp.
v1Lowercase 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.

Fail if the secret is missing

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).

Before you move money

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):

RAW BODY
{"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\":...}") = c7d4cce0739936c4214b5eda26b6602b27c85eae7f5940178cd8ec75ea02a013

You 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.

To rotate your secret without downtime:

  1. Update your code to accept both the current and the previous secret (both visible in Board)
  2. Deploy the updated code
  3. Rotate the secret in Board
  4. 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:

  1. Make your endpoint read the raw body (Step 1).
  2. Verify X-Minteo-Signature as described above. While you test it, you can keep checking the legacy checksum as well.
  3. Once it works, stop checking signature.checksum and X-Hook-Checksum.

The legacy checksum will be removed in the future. Minteo will announce the date in advance.

Legacy checksum (deprecated)​

Do not read signature.properties from the message

Earlier 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_typeFields, in order
order.updatedorder.id, order.status, order.amount
payout.updatedpayout.id, payout.status, payout.transfer_amount
payout.item.updatedpayout_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_item for payout.item.updated).
  • Check the format of the signed values before computing the checksum: the id is a UUID, the status is one of the documented values, the amount is numeric.
  • Reject messages whose timestamp is 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();
}

Next steps​