Verify webhook signatures

Each request includes X-Minisend-Signature: an HMAC-SHA256 hex of the raw JSON body, keyed with your webhook_secret. Verify it before processing.

Find your webhook_secret in Settings. Treat it like a password.

Use a timing-safe comparison. === is vulnerable to timing attacks.

Sign over the raw body

The signature covers the exact bytes Minisend sent. Re-stringifying the parsed body (JSON.stringify(req.body)) can produce different bytes and break verification. Capture the raw body before parsing. In Express, use express.raw({ type: 'application/json' }) for 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 deliveries also carry X-Minisend-Signature-V2, formatted as t=<timestamp>,v1=<hmac>. It signs the timestamp together with the body, so a signature captured off the wire can’t be replayed later the way one covering the body alone could be. X-Minisend-Signature isn’t going anywhere and still works everywhere; V2 exists for anyone who wants that extra guarantee.

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 delivery carries this header. Off-ramp, onramp, and Wallet API events only send X-Minisend-Signature, so check for X-Minisend-Signature-V2 and fall back to the V1 check above if it’s missing rather than requiring it everywhere.

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

Return 2xx before running business logic. Anything taking >10s triggers a retry.

Get Started

Dashboard

Payments

Off-ramp API

Onramp API

Wallet API

Webhooks

Help

Verify webhook signatures

Sign over the raw body

Verify

A stronger option: X-Minisend-Signature-V2

Full Express handler

​Sign over the raw body

​Verify

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

​Full Express handler

Sign over the raw body

Verify

A stronger option: X-Minisend-Signature-V2

Full Express handler