ethoca-webhooks

Ethoca Webhooks

Ethoca (a Mastercard company) delivers Alerts — early fraud and dispute notifications from issuers — to merchants. The Alerts Push API HTTPS-POSTs JSON to an endpoint you register with the Ethoca Customer Delivery Team.

When to Use This Skill

• How do I receive Ethoca Alerts webhooks (Push API)?
• How do I secure an Ethoca webhook endpoint without a signature header?
• How do I handle Ethoca fraud and dispute alerts?
• Why is there no X-Ethoca-Signature / HMAC header to verify?
• How does Ethoca mTLS (MSSL) delivery work?

Verification (core)

There is NO per-message HMAC/signature header on Ethoca Push API alerts. Do not look for X-Ethoca-Signature or a Standard Webhooks header — none exists. Trust is established primarily by the transport:

1. Transport — mutual TLS (MSSL) — the definitive check. Ethoca presents a client certificate; your server must trust the Entrust CA and require a client cert. This is enforced at your TLS terminator / load balancer, not in app code, and is the actual mechanism that authenticates the delivery.
2. Application — HTTP Basic Auth (OPTIONAL). If you agree Basic Auth credentials with the Ethoca Customer Delivery Team at onboarding, Ethoca sends Authorization: Basic base64(username:password) and your handler checks it. Whether Ethoca sends Basic Auth is not guaranteed by the API — an endpoint secured by mTLS alone may receive no Authorization header.

An IP allowlist of Ethoca's egress ranges is a recommended additional layer.

Enforce Basic Auth only when credentials are configured — if none are set, accept the delivery and rely on mTLS rather than returning 401. When configured, verify the credentials with a timing-safe comparison. Node:

const crypto = require('crypto');

function safeEqual(a, b) {
  const ab = Buffer.from(a), bb = Buffer.from(b);
  return ab.length === bb.length && crypto.timingSafeEqual(ab, bb);
}

function verifyEthocaAuth(authHeader, username, password) {
  if (!authHeader || !authHeader.startsWith('Basic ')) return false;
  const decoded = Buffer.from(authHeader.slice(6), 'base64').toString('utf-8');
  const i = decoded.indexOf(':');
  if (i === -1) return false;
  return safeEqual(decoded.slice(0, i), username) &&
         safeEqual(decoded.slice(i + 1), password);
}