nmi-webhooks

NMI Webhooks

When to Use This Skill

• How do I receive NMI (Network Merchants) webhooks?
• How do I verify the NMI Webhook-Signature header?
• Why is my NMI webhook signature verification failing?
• How do I handle transaction.sale.success, transaction.auth.success, transaction.refund.success, or transaction.void.success events?
• What is the t= value in the NMI signature header — is it a timestamp?

How NMI Webhooks Work (Read This First)

NMI does not use the Standard Webhooks spec. Each delivery carries a single custom header:

Webhook-Signature: t=f3c1e9a2b7d84c15,s=9b7c...e10a

Two facts drive everything below:

1. t is a NONCE, not a timestamp. It is a random value NMI generates per delivery and includes in the signed content. Because it is not a timestamp, NMI documents no replay/timestamp tolerance window — do not try to reject "old" deliveries by parsing t as a Unix time.
2. The signature signs "<nonce>.<raw_body>". You verify by computing HMAC-SHA256 over the nonce, a literal ., and the raw, unparsed request body, keyed with your signing key, hex-encoding it, and comparing (timing -safe) to the s value. Re-serializing the JSON breaks the HMAC.

NMI ──POST body + "Webhook-Signature: t=<nonce>,s=<hex>"──▶ your endpoint
                                                             │  parse t + s
                                                             │  hmac_sha256(key, t + "." + rawBody)
                                                             ▼
                                              timing-safe compare hex == s → 200

The payload envelope is { "event_id", "event_type", "event_body" }. The event_type is a dotted lowercase string like transaction.sale.success.

Verification (core)

const crypto = require('crypto');

// Header: "Webhook-Signature: t=<nonce>,s=<lowercase-hex-hmac>"
// t is a NONCE (not a timestamp); the signed content is `<nonce>.<rawBody>`.
function verifyNmiWebhook(rawBody, signatureHeader, signingKey) {
  const parts = {};
  for (const seg of String(signatureHeader || '').split(',')) {
    const i = seg.indexOf('=');
    if (i !== -1) parts[seg.slice(0, i).trim()] = seg.slice(i + 1).trim();
  }
  const { t: nonce, s: signature } = parts;
  if (!nonce || !signature || !signingKey) return false;

  const body = Buffer.isBuffer(rawBody) ? rawBody.toString('utf8') : rawBody;
  const expected = crypto
    .createHmac('sha256', signingKey)
    .update(`${nonce}.${body}`)
    .digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  } catch {
    return false; // length mismatch = invalid
  }
}