Receiving

POST {your callbackUrl}
Content-Type: application/json
Activation-Code: {your activation code}

{ "Token": "<compact JWE>" }

const jose = require('node-jose');

app.post('/webhooks/modulus', async (req, res) => {
  let payload;
  try {
    // Decrypt the Token with your ENCRYPTION KEY (not the Secret Key)
    const keystore = jose.JWK.createKeyStore();
    // Encryption Key is base64 - decode to raw octets before adding
    const key = Buffer.from(process.env.MODULUS_ENCRYPTION_KEY, 'base64');
    await keystore.add(key, 'oct');
    const { plaintext } = await jose.JWE.createDecrypt(keystore).decrypt(req.body.Token);
    payload = JSON.parse(plaintext.toString());
  } catch (err) {
    // A body you cannot decrypt is not one we sent, or the wrong key. Do not return 200.
    return res.status(400).json({ error: 'decrypt_failed' });
  }

  // Deduplicate: retries reuse the same body, so the (transactionId, webhookAction) pair repeats
  const key = `${payload.transactionId}:${payload.webhookAction ?? ''}`;
  if (await alreadyProcessed(key)) return res.status(200).json({ received: true });

  // Durably record the event BEFORE acknowledging - once you return 200 there is no retry
  await markProcessed(key);
  res.status(200).json({ received: true });
  await handleTransaction(payload); // correlate on payload.merchantReferenceNumber
});

# Allow webhook traffic from Modulus IPs only
iptables -A INPUT -p tcp --dport 443 -s <MODULUS_IP_RANGE> -j ACCEPT