# Set Up Your Webhook
source: https://developer.mastercard.com/transaction-notifications/documentation/tutorials-and-guides/webhook/index.md

Set up a webhook endpoint to receive real-time transaction notifications from Mastercard when authorization or clearing events occur on enrolled cards.

## Before You Begin {#before-you-begin}

Confirm the following:

* You have enrolled a card through [Consent Management \& Enrollment](https://developer.mastercard.com/consent-management/documentation/) and obtained a `cardReference`.
* You have an HTTPS endpoint that can accept `POST` requests with JSON data.
* Your endpoint supports mutual TLS (MTLS) authentication. If you have SSL certificates issued by an external certificate authority, provide details during integration for Mastercard to validate support.

Tip: To secure your endpoint, add the Mastercard outbound NAT addresses to your allowlist and implement MTLS verification. Contact [transaction.notifications@mastercard.com](mailto:transaction.notifications@mastercard.com) for IP details and client certificates.

## Configure Your Webhook Endpoint {#configure-your-webhook-endpoint}

1. Register your webhook URL during onboarding.

2. Implement your endpoint to return an HTTP 200 status code immediately upon receiving a notification. Include a JSON response body with a `success` boolean set to `true`.

   Note: Do not perform data field validation before sending the acknowledgment. Perform all validation asynchronously on a separate thread so that it does not affect the transaction notification response. Responding with a validation error causes the transaction notification delivery to fail.
3. Handle duplicate notifications. Connection drops or timeouts can cause the retry mechanism to generate duplicate notifications. To deduplicate:

   * **Authorization notifications:** use the `transUid` field, which is unique for each authorization notification. If `transUid` is not present, use a combination of `cardReference`, `transmissionDate`, `transmissionTime`, `financialNetworkCode`, and `referenceNumber`.

   * **Clearing notifications:** use the `clearingUniqueId` field, which is unique for each clearing notification.

4. Decrypt payloads if required. By default, notification payloads are delivered as plain-text JSON. If your configuration includes sensitive data (for example, PAN or expiry date), Mastercard encrypts the payload using [JSON Web Encryption (JWE)](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/). Use [Mastercard client encryption libraries](https://github.com/Mastercard?q=client-encryption) to decrypt the payload.

## Understand Retry and Delivery Persistence {#understand-retry-and-delivery-persistence}

If your webhook endpoint does not return an HTTP 2XX response, Mastercard marks the delivery as failed and retries at progressive intervals for up to 24 hours. After 24 hours, undelivered notifications are stored for up to seven days and can be retrieved using the [Retrieve Undelivered Notifications](https://developer.mastercard.com/transaction-notifications/documentation/use-cases/retrieve-undelivered-notifications/index.md) endpoint. The endpoint returns 100 notifications at a time using cursor-based pagination with the `after` parameter.

## Configure Multiple Webhooks {#configure-multiple-webhooks}

If you need to separate webhooks by market region or use case, you can register multiple webhook endpoints during onboarding. Mastercard assigns a unique webhook selector to each URL to route notifications correctly.

For example, if your user base spans Europe and the United States and you operate separate regional servers, you can configure distinct webhooks for each region:

| Webhook Endpoint                       | Webhook Selector |
|:---------------------------------------|:-----------------|
| <https://us.fintech.com/notifications> | FINTECH-US       |
| <https://eu.fintech.com/notifications> | FINTECH-EU       |

### Assign a Webhook Selector During Enrollment {#assign-a-webhook-selector-during-enrollment}

Specify the appropriate webhook selector when enrolling cardholders through [Consent Management \& Enrollment](https://developer.mastercard.com/consent-management/documentation/) APIs.

#### Consent API Enrollments {#consent-api-enrollments}

For example, when creating consent for a US cardholder to receive notifications on your US endpoint:

```json
{
  "consents": [
    {
      "name": "notification",
      "details": {"webhookSelector": "FINTECH-US", "businessName": "BusinessA"}
    }
  ],
  "cardDetails": {
    ...
  }
}
```

#### Mastercard UI Enrollments {#mastercard-ui-enrollments}

Pass the webhook selector in the JWT payload:

```json 
JWT Payload:
{
  "exp": 1583760792,
  "iat": 1583758992,
  "jti": "cb",
  "nbf": 1583758992,
  "appdata": {
    "callbackURL": "https://fintech.com",
    "consents": [
      {
        "name": "notification",
        "details": {"webhookSelector": "FINTECH-US", "businessName": "BusinessA"}
        ...
      }
    ]
  }
}
```

#### Bulk Card Enrollments {#bulk-card-enrollments}

```json 
{
  "cards": [
    {
      "accountNumber": "511XXXXXXXXXX444",
      "recId": "R1",
      "expiry": "01/2027"
    }
  ],
  "consents": {
    "notification": {
      "webhookSelector": "FINTECH-US",
      "businessName": "BusinessA"
      ...
    }
  }
}
```

## Next Steps {#next-steps}

* Review the [Transaction Notifications Webhook API](https://developer.mastercard.com/transaction-notifications/documentation/api-reference/transaction-notification-webhook/index.md) specification for the full notification payload schema.
* [Create a test transaction](https://developer.mastercard.com/transaction-notifications/documentation/tutorials-and-guides/test-transaction/index.md) to verify your webhook receives notifications correctly.
* Explore [Retrieve Clearing Data](https://developer.mastercard.com/transaction-notifications/documentation/tutorials-and-guides/clearing-data/index.md) to fetch settled transaction data.