paymob-webhooks

Paymob Webhooks

When to Use This Skill

• How do I receive Paymob webhooks (transaction callbacks)?
• How do I verify a Paymob HMAC signature?
• Why is my Paymob HMAC verification failing?
• How do I tell if a Paymob transaction succeeded, was refunded, or voided?
• Understanding the difference between the Transaction Processed Callback (POST) and Transaction Response Callback (GET)

Verification (core)

Paymob does not use Standard Webhooks, and it does not sign the raw body. Instead it computes HMAC-SHA512 over a fixed, ordered concatenation of 20 specific fields (no separators), hex-encodes it, and sends the result as the hmac query parameter on the callback URL (?hmac=<hex>). Use the HMAC secret from your Paymob dashboard.

The 20 fields, in this exact order, are read from the transaction object (obj in the POST payload): amount_cents, created_at, currency, error_occured, has_parent_transaction, id, integration_id, is_3d_secure, is_auth, is_capture, is_refunded, is_standalone_payment, is_voided, order.id, owner, pending, source_data.pan, source_data.sub_type, source_data.type, success.

Node (Transaction Processed Callback / POST, JSON body):

const crypto = require('crypto');

// obj = parsed request body `obj` field; hmacParam = req.query.hmac
function verifyPaymobHmac(obj, hmacParam, secret) {
  const s = obj.source_data || {};
  const signed = [
    obj.amount_cents, obj.created_at, obj.currency, obj.error_occured,
    obj.has_parent_transaction, obj.id, obj.integration_id, obj.is_3d_secure,
    obj.is_auth, obj.is_capture, obj.is_refunded, obj.is_standalone_payment,
    obj.is_voided, obj.order.id, obj.owner, obj.pending,
    s.pan, s.sub_type, s.type, obj.success,
  ].join(''); // JS renders booleans as "true"/"false", numbers as their digits
  const expected = crypto.createHmac('sha512', secret).update(signed).digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(hmacParam || ''));
  } catch { return false; }
}