# Creditor Agent Webhook Notifications
source: https://developer.mastercard.com/payment-acceptance-api/documentation/use-cases/event-notifications/index.md

## Creditor Agent Webhook Notifications {#creditor-agent-webhook-notifications}

Event notifications provide near real-time payment status updates by delivering events to an Agent-managed webhook endpoint. A webhook is required for status updates and must support the security requirements described below.

### Endpoint coverage {#endpoint-coverage}

This use case explicitly covers the API Reference operation `POST /creditor-agents/notifications` to ensure one-to-one coverage between API Reference operations and Use Cases.

## Setting Up mTLS for Event Notifications {#setting-up-mtls-for-event-notifications}

CDP delivers notifications to the Agent webhook using mTLS. To enable mTLS, ensure that you:

1. Have a Mastercard-trusted certificate authority (CA) for the certificate presented by the Agent endpoint.
2. Request access to the Key Management Portal (KMP) in Mastercard Connect (used to obtain the required outbound certificate chain information).
3. Load the API Gateway (APIGW) outbound certificate details into the Agent trust store so the Agent can trust the outbound caller for notifications.

## How Event Notifications Work {#how-event-notifications-work}

CDP sends notifications to the Agent event notification URL when a Creditor Agent updates a payment instruction status. CDP can also send responses to registration or discovery-related requests to the same event notification URL.

Provide the event notification URL during onboarding. For example, an event notification URL could be:
`https://companyname.com/cdp/notifications`

### Use case: Receive and acknowledge an event notification (Webhook) {#use-case-receive-and-acknowledge-an-event-notification-webhook}

This scenario demonstrates how an Agent receives an event notification and returns an acknowledgment within the required SLA.

#### Step-by-step flow {#step-by-step-flow}

1. **Expose the webhook endpoint**


   API Reference: `POST /creditor-agents/notifications`

   .

   <br />

2. **Provide environment-specific webhook URLs during onboarding** (for example, separate URLs for Sandbox and Production; subpaths are recommended to isolate CDP notifications from other traffic).

3. **Establish mTLS trust for outbound notifications** (Agent trusts the APIGW outbound certificate chain; Mastercard trusts the Agent CA where applicable).

4. **Receive the notification payload** at the webhook URL.

5. **Return an acknowledgment within 3 seconds.**   

   If CDP does not receive an acknowledgment within **3 seconds** , CDP retries the notification three times at **30-second intervals** . If no response is received after these retries, CDP updates the status to **CREDITOR_AGENT_SYSTEM_ERROR**.

### Event types and payload envelope {#event-types-and-payload-envelope}

Each event notification includes an event type that identifies the data contained in the notification. The data schema varies based on the event type.

![Diagram showing the structure of a Notification object, containing Event Identifier, Event Type, Event Created Date, and a Data block. The Data block includes transaction ID and event-specific data.](https://static.developer.mastercard.com/content/payment-acceptance-api/uploads/webhooknotification.png "Event Notification Structure")

All CDP use cases use the following event notification payload structure. The `data` object schema differs based on the event type. Refer to the relevant use-case section for schema details.

```JSON
{
  "eventId": "string",
  "eventType": "string",
  "eventCreatedDate": "datetime",
  "data": {
  }
}
```