# 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:

```javascript
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);
}

```

> No body signature means the raw request body is not security-critical here,
> so ordinary JSON parsing is fine (unlike HMAC-based providers). Authenticity
> comes from mTLS + Basic Auth on the connection, not from the payload bytes.

> Outbound outcomes are different. When you report an alert outcome back to
> Ethoca via the Outcome API, that call uses OAuth 1.0a with a PKCS#12
> (`.p12`) keystore and the [`mastercard-oauth1-signer`](https://github.com/Mastercard/oauth1-signer-nodejs)
> helper — see [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/ethoca-webhooks/references/verification.md). The
> sibling product Ethoca Consumer Clarity uses a different `ETHOCA-SHA1`
> HMAC scheme; do not apply it here.

> For complete handlers with route wiring, event dispatch, and tests, see:
> 
> * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/ethoca-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/ethoca-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/ethoca-webhooks/examples/fastapi/)

## Alert Categories

Ethoca alerts fall into two categories, carried in the `alertType` field:

| `alertType` | Meaning | Common Use Cases |
| --- | --- | --- |
| `fraud` | Issuer flagged the transaction as confirmed/suspected fraud | Stop fulfilment, refund, cancel subscription, block account |
| `dispute` | Cardholder initiated a dispute / pre-chargeback | Refund to avoid a chargeback, gather evidence, update order |

> Verify literal values at onboarding. The exact `alertType` enum is not
> published publicly and has historically been numeric. Confirm the values in
> your Ethoca onboarding schema and normalize to the two categories above — see
> [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/ethoca-webhooks/references/overview.md).

## Environment Variables

Optional — set both only if you agreed Basic Auth credentials at onboarding.
Leave them unset for an mTLS-only endpoint (the handler then skips the Basic Auth
check instead of returning `401`).

```bash
ETHOCA_WEBHOOK_USERNAME=your_basic_auth_username   # Optional; agreed with Ethoca onboarding
ETHOCA_WEBHOOK_PASSWORD=your_basic_auth_password   # Optional; agreed with Ethoca onboarding

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 ethoca --path /webhooks/ethoca

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/ethoca-webhooks/references/overview.md) - Ethoca Alerts concepts, payload, `alertType`
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/ethoca-webhooks/references/setup.md) - Endpoint registration with the Customer Delivery Team
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/ethoca-webhooks/references/verification.md) - mTLS, Basic Auth, and the OAuth 1.0a Outcome API