Guides
Start typing to search…

Webhooks API Concepts

The mCards platform uses webhooks to deliver real-time events to partner systems. Webhooks allow mCards to notify partners when important events occur and, in some cases, to request partner participation in transaction decisioning.

This guide describes the conceptual model for webhooks on the mCards platform, including event types, delivery behavior, and webhook security.

What Are Webhooks in mCards?

Webhooks are HTTP callbacks sent by the mCards platform to partner-defined endpoints when specific events occur.

Webhooks are used to:

  • Notify partners of platform events
  • Enable partners to react to transactions in real time
  • Allow payment gateway providers to participate in authorization decisioning

Webhooks are a core integration mechanism for the Payments API and are also used for other platform events.

When Webhooks Are Used

Webhooks are delivered whenever an event occurs that a partner has subscribed to.

Common use cases include:

  • Transaction authorization events
  • Transaction completion events
  • Payment account lifecycle events
  • Feature-related or offer-related events (where applicable)

Partners control which events they receive by creating webhook subscriptions.

Webhook Subscription Model

Partners receive webhook notifications by creating webhook subscriptions using the Webhooks API.

Each webhook subscription defines:

  • The event type to subscribe to
  • The destination URL where events are delivered
  • The security configuration used to authenticate webhook requests
  • The active or inactive status of the webhook

Multiple webhook subscriptions may be created by a single partner.

Webhook Event Types

mCards supports multiple webhook event types. Common categories include:

Transaction Events

Transaction events notify partners about activity related to card transactions.

Examples include:

  • Authorization events
  • Completion events
  • Single-message transaction events

Transaction events are critical for payment gateway providers that participate in authorization decisioning.

Payment Account Events

Payment account events notify partners when payment accounts are created, updated, or changed.

These events allow partners to:

  • Track the lifecycle of payment accounts
  • Maintain synchronization between systems

Other Event Types

Depending on the integration, additional event types may be available, such as feature or offer-related events.

Partners should consult the API reference for the complete list of supported event types.

Webhooks and Authorization Decisioning

For payment accounts created using the Payments API, webhooks play an active role in transaction authorization.

During transaction processing:

  1. mCards receives an authorization request from the card network
  2. The Dynamic Processing Engine (DPE) evaluates payment accounts in rank order
  3. For payment accounts backed by a payment gateway:
    • mCards sends an authorization webhook to the payment gateway
    • The webhook requests an approve or decline decision
  4. The payment gateway responds to the webhook
  5. mCards uses the response to determine whether to approve the transaction or move to the next payment account

In this model, the payment gateway is an active participant in authorization decisioning.

Webhook Delivery Behavior

Webhook notifications are delivered as HTTP POST requests to the partner’s configured endpoint.

Delivery characteristics include:

  • JSON-formatted request bodies
  • Event-specific payloads
  • Headers conveying security and metadata

Partners should ensure webhook endpoints are:

  • Highly available
  • Capable of processing requests quickly
  • Designed to handle retries or duplicate events where applicable

Webhook Security Overview

Webhook notifications are sent from mCards to partner systems and must be authenticated by the receiving partner.

Webhook security is separate from API authentication and uses webhook-specific secrets.

Webhook Authentication Methods

When creating a webhook subscription, partners configure one or more authentication mechanisms.

Common mechanisms include:

  • Basic authentication
  • HMAC-based signatures

These mechanisms are configured per webhook subscription.

HMAC Signature for Webhook Notifications

mCards supports HMAC-based signatures to allow partners to verify the authenticity and integrity of webhook notifications.

Signature Header

When HMAC signing is enabled, webhook notifications include the following HTTP header:

  • Header name: X-Webhook-Signature
  • Header value format: HMAC_SHA256 {hmac_key};{hmac_signature}

How the Signature Is Generated

At a conceptual level:

  • mCards generates an HMAC SHA-256 signature
  • The signature is computed over the raw JSON request body
  • The webhook-specific secret is used as the signing key

The HMAC secret is provided by the partner when creating the webhook subscription and is stored securely by mCards.

Partner Verification Responsibilities

Partners receiving webhook notifications should:

  1. Extract the X-Webhook-Signature header
  2. Recompute the HMAC signature using the webhook secret
  3. Compare the computed signature with the received signature
  4. Reject the request if validation fails

This process ensures that webhook notifications originate from mCards and have not been tampered with.

Webhook Secrets vs API Credentials

Webhook secrets and API credentials serve different purposes and must not be conflated.

Webhook Secrets

  • Used to verify mCards-to-partner webhook notifications
  • Configured per webhook subscription
  • Never used for API authentication

API Credentials

  • Used to authenticate partner-to-mCards API requests
  • Shared across APIs
  • Described in the API Authentication & Credentials guide

Partners should manage webhook secrets and API credentials independently.

Webhook Reliability Considerations

Partners should design webhook endpoints with the following considerations:

  • Idempotent processing of events
  • Proper handling of duplicate notifications
  • Fast response times to avoid timeouts
  • Monitoring and alerting for failed deliveries

Webhook delivery behavior and retry policies are described in the API reference documentation.

Related Guides

  • Platform Concepts
    Transaction processing and authorization flow.

  • API Authentication & Credentials
    Authentication for partner-to-mCards API requests.

  • Payments API Concepts
    How payment gateways participate in authorization using webhooks.

Next step

Continue to Payments API Concepts to understand how payment accounts are created and how payment gateways integrate with mCards transaction processing.

Updated about 2 months ago