Guide to Ethoca Webhooks: Features and Best Practices

Ethoca (Mastercard) alerts notify merchants about fraud and dispute activity so you can stop fulfillment or issue refunds before a chargeback lands. If you're building on Ethoca Alerts, the Push API delivers those alerts to your endpoint, but with a trust model unlike most webhooks.

This guide covers how Ethoca Alerts Push webhooks work, the mTLS trust model (there's no per-message signature), the alert categories, and the best practices for production.

What are Ethoca webhooks?

The Ethoca Alerts Push API HTTPS-POSTs JSON alerts to a merchant endpoint (a legacy pull/queue model also exists). The critical thing to understand: there is no per-message HMAC or signature header on Push alerts. Trust rests on the mutual-TLS (mTLS) channel, not a verifiable payload signature.

Ethoca webhook features

Alert categories

Ethoca alerts fall into two categories:

An alertType field exists, but Ethoca doesn't publish its literal enum values (historically numeric), so branch on the category and treat the alert data defensively.

Setting up Ethoca webhooks

Endpoints are registered manually by the Ethoca Customer Delivery Team, there's no self-serve UI. Setup involves configuring the mutual-TLS relationship (your endpoint trusts the Entrust CA, and Ethoca is configured to present its client certificate). Your own outbound Outcome API calls (to report what you did about an alert) use OAuth 1.0a with a PKCS#12 keystore.

Securing Ethoca webhooks

There's no signature to verify. The Push API's authenticity comes entirely from the mutual-TLS channel: your endpoint requires and validates Ethoca's client certificate, and Ethoca validates yours. Configure mTLS at your TLS-terminating layer (load balancer, reverse proxy, or the app server).

# Illustrative: enforce mTLS at the proxy (nginx)
server {
  listen 443 ssl;
  ssl_client_certificate /etc/ssl/ethoca-entrust-ca.pem;  # trust the Entrust CA
  ssl_verify_client on;                                    # require Ethoca's client cert
  ...
  location /ethoca-alerts {
    proxy_pass http://app;   # only mTLS-authenticated requests reach the app
  }
}

At the application layer, then, you accept the JSON alert and process it, there's no HMAC step. Do not look for (or invent) a signature header.

Ethoca's sibling product, Consumer Clarity, uses a different scheme with an HMAC header (Authorization: ETHOCA-SHA1 KeyRef=<id>,Signature=<base64url>). Don't apply that to Alerts Push, they're separate products.

Ethoca webhook limitations and pain points

No per-message signature, trust is the mTLS channel

The Problem: There's no HMAC or signature header to verify on Push alerts. If your mTLS isn't correctly enforced, you have no per-message way to prove an alert came from Ethoca, and there's no signature to fall back on.

Why It Happens: Ethoca secures Push delivery with mutual TLS rather than payload signing.

Workarounds:

• Enforce mTLS strictly (require and validate Ethoca's client cert against the Entrust CA) at your TLS layer; restrict the endpoint accordingly.

How Hookdeck Can Help: Hookdeck gives you a dedicated ingestion endpoint and can enforce authentication and filtering in front of your app, adding a verification layer where Ethoca provides only the channel.

Manual, team-managed registration

The Problem: There's no self-serve setup, the Ethoca Customer Delivery Team registers endpoints and configures the mTLS relationship, which slows changes.

Why It Happens: Ethoca manages Alerts integrations manually.

Workarounds:

• Coordinate with the Ethoca Customer Delivery Team for endpoint and certificate configuration.

How Hookdeck Can Help: Hookdeck gives you a stable endpoint to register once, so your side of the configuration stays fixed.

Don't conflate with Consumer Clarity

The Problem: Ethoca Consumer Clarity uses an HMAC header (ETHOCA-SHA1). Applying that scheme to Alerts Push (which has no signature) means looking for a header that isn't there.

Why It Happens: Two Ethoca products use different trust models.

Workarounds:

• For Alerts Push, rely on mTLS; use the HMAC scheme only for Consumer Clarity.

How Hookdeck Can Help: Hookdeck can ingest either product and normalize them, so downstream consumers aren't reasoning about which scheme applies.

Reporting outcomes uses a different auth

The Problem: Your inbound alerts are mTLS-only, but your outbound Outcome API calls (reporting what you did) use OAuth 1.0a with a PKCS#12 keystore, a separate mechanism to implement.

Why It Happens: Ethoca uses OAuth 1.0a for merchant-initiated API calls.

Workarounds:

• Implement the OAuth 1.0a signing (the mastercard-oauth1-signer helper exists) for outbound calls, separate from inbound mTLS.

How Hookdeck Can Help: Hookdeck durably queues inbound alerts, giving your worker room to make the authenticated Outcome API call reliably.

Best practices

Enforce mTLS strictly

Require and validate Ethoca's client certificate against the Entrust CA at your TLS-terminating layer; this is the only per-request trust signal.

Don't look for a signature header on Push alerts

There isn't one, use mTLS, and use the HMAC scheme only for Consumer Clarity.

Acknowledge fast, process asynchronously

Accept the alert, return 2xx, and process off a queue. See why to process webhooks asynchronously.

Dedupe and report outcomes

Dedupe alerts, and report your action via the OAuth 1.0a Outcome API.

Conclusion

Ethoca Alerts Push webhooks have no per-message signature, trust is the mutual-TLS channel, so enforce mTLS strictly and don't look for a header that isn't there (that HMAC scheme belongs to the separate Consumer Clarity product). Registration is manual, and your outbound Outcome API calls use OAuth 1.0a.

Hookdeck adds verification and filtering in front of Ethoca's mTLS channel, deduplicates, and durably queues every alert at the edge, so your app processes trustworthy alerts and has room to report outcomes reliably.

Get started with Hookdeck for free and handle Ethoca webhooks reliably in minutes.