Verify webhook signatures

Anyone can send a request to your webhook URL, so before you act on one, check it really came from us. Every message we send has an X-Minisend-Signature header. It’s a fingerprint of the message body made with your webhook_secret (technically, an HMAC-SHA256 hex digest). You make the same fingerprint on your side, and if the two match, the message is genuine.

Find your webhook_secret under Dashboard → Webhooks. Treat it like a password.

Compare the two with a timing-safe function, like the ones in the examples below. A plain === can leak information to an attacker through how long it takes.

Use the raw body

The signature is made from the exact text we sent. If you parse the JSON and turn it back into text (JSON.stringify(req.body)), the spacing or order can change and the check will fail. So grab the raw body before your framework parses it. In Express, use express.raw({ type: 'application/json' }) on the webhook route.

Verify

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');

  const a = Buffer.from(signature, 'hex');
  const b = Buffer.from(expected, 'hex');

  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

import hmac, hashlib

def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

<?php
function verifyWebhook(string $rawBody, string $signature, string $secret): bool {
    $expected = hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signature);
}

A stronger option: X-Minisend-Signature-V2

Checkout and settlement messages also come with X-Minisend-Signature-V2, in the form t=<timestamp>,v1=<signature>. It includes the time we sent the message, so if someone copied an old message, they couldn’t send it to you again later. X-Minisend-Signature is staying and works everywhere. V2 is there if you want the extra protection.

function verifyWebhookV2(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (age > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(parts.v1, 'hex');
  const b = Buffer.from(expected, 'hex');
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

Not every message has this header. Off-ramp, onramp, and Wallet API events only send X-Minisend-Signature. So use V2 when it’s there, and fall back to the first check when it isn’t.

Full Express handler

const express = require('express');
const crypto = require('crypto');
const app = express();

// Raw body required for signature verification
app.use(
  '/webhooks/minisend',
  express.raw({ type: 'application/json' }),
);

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
  const a = Buffer.from(signature, 'hex');
  const b = Buffer.from(expected, 'hex');
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/minisend', (req, res) => {
  const signature = req.headers['x-minisend-signature'];
  if (!signature) return res.status(401).json({ error: 'Missing signature' });

  if (!verifyWebhook(req.body, signature, process.env.MINISEND_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const payload = JSON.parse(req.body.toString('utf8'));

  // Acknowledge immediately, then process
  res.status(200).send('OK');

  switch (payload.event) {
    case 'checkout.completed':
      markOrderPaid(payload.external_id, {
        session_id: payload.session_id,
        receipt: payload.receipt,
        amount_local: payload.amount_local,
        currency: payload.currency,
      });
      break;
    case 'checkout.failed':
      handleFailedPayment(payload.external_id, payload.session_id);
      break;
    case 'checkout.expired':
      handleExpiredSession(payload.external_id, payload.session_id);
      break;
  }
});

app.listen(3000);

Reply with 2xx first, then do your own processing. If you take more than 10 seconds to reply, we’ll send the message again.

Get Started

Dashboard

Payments

Off-ramp API

Onramp API

Wallet API

Webhooks

Help

Verify webhook signatures

Use the raw body

Verify

A stronger option: X-Minisend-Signature-V2

Full Express handler

​Use the raw body

​Verify

​A stronger option: X-Minisend-Signature-V2

​Full Express handler

Use the raw body

Verify

A stronger option: X-Minisend-Signature-V2

Full Express handler