Webhooks API Concepts

The Webhooks API allows partners to register HTTP endpoints that receive real-time event notifications from the mCards platform. Webhooks are used for transaction events, location updates, offer claims, and payment authorization.

Webhook Registration

Each webhook registration includes:

Each webhook registration is scoped to a single event type. To receive multiple event types, register multiple webhooks.

Event Types

Standard Events

Payment Events

Payment events are used for real-time authorization with payment gateway integrations:

See Payments API Concepts for the full authorization flow.

Event Type Availability

Not all event types are available to all partners. Availability depends on your integration type:

Partners with access to multiple APIs receive the union of all event types across their integration types. See API Scoping and Permissions for full details.

Webhook Payload Examples

All webhook deliveries are HTTP POST requests with a JSON body. Every payload includes a webhook_event_type field indicating the event type.

Transaction Event Payload

{
  "webhook_event_type": "transaction",
  "card_transaction_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": 42.50,
  "currency_code": "USD",
  "created_at": "2025-03-15T14:22:31.000Z",
  "updated_at": "2025-03-15T14:22:31.000Z",
  "cardholder_card_uuid": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
  "location": {
    "location_uuid": "11223344-5566-7788-99aa-bbccddeeff00",
    "name": "Corner Coffee Shop",
    "full_address": "123 Main St, Anytown, US 12345",
    "latitude": 40.7128,
    "longitude": -74.0060
  },
  "claimed_offer": {
    "claimed_offer_uuid": null,
    "title": null,
    "amount": null,
    "offer_uuid": null,
    "offer_reward": {
      "title": null,
      "subtitle": null,
      "summary": null,
      "amount_type": null,
      "amount_currency": null
    },
    "created_at": null,
    "updated_at": null
  }
}

The claimed_offer object is always present but its fields are null when no offer was redeemed during the transaction.

Location Event Payload

{
  "webhook_event_type": "location",
  "event": "location",
  "source": "gps",
  "user_uuid": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "timestamp": "2025-03-15T14:30:00Z",
  "data": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "accuracy": 10.0,
    "altitude": 15.2,
    "speed": 0.0
  }
}

Claimed Offer Event Payload

{
  "webhook_event_type": "claimed_offer",
  "card_transaction_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transaction_amount": 42.50,
  "created_at": "2025-03-15T14:22:31.000Z",
  "updated_at": "2025-03-15T14:22:31.000Z",
  "cardholder_card_uuid": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
  "claimed_offer_state": "hold",
  "claimed_offers": [
    {
      "claimed_offer_uuid": "cc112233-4455-6677-8899-aabbccddeeff",
      "title": "10% Off Your Next Purchase",
      "amount": 4.25,
      "offer_uuid": "dd112233-4455-6677-8899-aabbccddeeff",
      "offer_reward": {
        "title": "10% Cashback",
        "subtitle": "Earn cashback on qualifying purchases",
        "summary": "10% cashback reward",
        "amount_type": "percentage",
        "amount_currency": "USD"
      },
      "created_at": "2025-03-15T14:22:31.000Z",
      "updated_at": "2025-03-15T14:22:31.000Z"
    }
  ],
  "location": {
    "location_uuid": "11223344-5566-7788-99aa-bbccddeeff00",
    "name": "Corner Coffee Shop",
    "full_address": "123 Main St, Anytown, US 12345",
    "latitude": 40.7128,
    "longitude": -74.0060
  }
}

The claimed_offer_state reflects the transaction lifecycle:

Payment Event Payload

Payment events (payment.hold, payment.capture, etc.) are delivered to payment gateway providers during real-time authorization. See Payments API Concepts for the full authorization flow and expected response format.

Delivery Security

mCards secures webhook deliveries using two mechanisms:

Basic Authentication

Every webhook delivery includes a Basic authorization header using the basic_auth_username and basic_auth_secret you provide during registration. Your endpoint should validate these credentials on every request.

HMAC Signature Verification

Each delivery also includes an HMAC signature computed from the request body using the hmac_secret you provide. To verify:

1. Read the raw request body
2. Compute HMAC-SHA256(hmac_secret, request_body)
3. Compare the computed signature with the one included in the request header
4. Reject the request if signatures do not match

This ensures the payload has not been tampered with and originated from mCards.

Delivery Behavior

• Webhooks are delivered as HTTP POST requests to your registered URL
• Your endpoint should respond with a 2xx status code to acknowledge receipt
• Non-2xx responses or timeouts may trigger retries (see Error Handling and Reliability)
• Payment authorization webhooks (payment.*) require a timely response — the cardholder is waiting at the point of sale

Best Practices

1. Respond quickly — Especially for payment events, minimize processing time before returning a response
2. Validate signatures — Always verify HMAC signatures to ensure request authenticity
3. Handle duplicates — Design your handler to be idempotent in case of retried deliveries
4. Use HTTPS — All webhook URLs must use HTTPS for secure transport
5. Monitor availability — Webhook failures may result in missed events; monitor your endpoint health

Related Guides

• Payments API Concepts — Payment gateway authorization flow
• API Scoping and Permissions — Webhook entitlements by integration type
• API Authentication and Credentials — HMAC authentication for API requests
• Webhooks API Reference — Full endpoint documentation