# How to configure event notifications
source: https://developer.mastercard.com/track-search/documentation/tutorials-and-guides/event-notifications-tutorial/index.md

## Overview {#overview}

Mastercard Track Search uses event notifications to notify you with the `bulkSearchId` of your bulk search request when your request has completed processing. You can configure a Notification URL to receive notifications. Once you receive the notification, you can then proceed to retrieve results for your completed search request using the `bulkSearchId`.

The purpose of this tutorial is to provide you a consolidated set of implementation instructions and guidelines to assist with the event notification setup.
>
> #### What you will learn {#what-you-will-learn}
>
> * How to receive a Mastercard Trusted CA
> * How to gain access tot he Key Management Portal, and
> * How to load your certificate into the trust store

### How event notifications work {#how-event-notifications-work}

Mastercard presents its client certificate when requested by the server to authenticate and establish a trusted connection before sending the notification to your event notification URL. Search sends notifications to your event notification URL when bulk requests are completed.

You should provide the URL of the event notification during onboarding. An example event notification URL could be `https://companyname.com/search/notifications`. When Search sends an event notification to your URL, Search expects an acknowledgement within three seconds. If Search does not receive an acknowledgement within three seconds, then Search updates the status to `<COMPLETED>`.

Each event notification has an event type to identify the data within the notification. The data schema changes based on the event type.

![alt text](https://static.developer.mastercard.com/content/track-search/uploads/webhooknotification.png "Event Notification Information Flow")

## Basic event notification setup process {#basic-event-notification-setup-process}

###### 1. Customer Setup {#1-customer-setup}

Self service process of Company ID and Billable ICA to establish the company profile.

###### 3. Integration and Security {#3-integration-and-security}

Request a client certificate and establish MTLS with our APIs.

## Technologies used {#technologies-used}

* [Mastercard Connect](https://www.mastercardconnect.com/mccpblcui/#/public/signin)

## What you will achieve {#what-you-will-achieve}

You will create and load the certificates necessary for creating your event notification URL.

## Customer Setup {#customer-setup}

To set your company up as a customer, it must have an assigned:

* Company ID (CID) with Mastercard
* Billable ICA

A CID will provide access to the key Management portal to request and exchange the necessary certificates.

Obtaining a Company ID (CID) is a self-service process through the Mastercard Connect portal.
Follow the below steps to obtain a CID:

1. Go to [Mastercard Connect](https://www.mastercardconnect.com/mccpblcui/#/public/signin) and then click **Sign Up**.

2. Follow the prompts to sign up. Sign up for merchants is simplified into three sections:

   * Your Account
   * About you
   * About your company

### Your account (new users create an account -- no SecurID needed) {#your-account-new-users-create-an-account--no-securid-needed}

* Begin creating a User ID, Password, and Security question.
* Please adhere to the password requirements while creating one.

### About You (tell us about you and accept terms of use) {#about-you-tell-us-about-you-and-accept-terms-of-use}

* Please provide us with the user information and proceed by accepting the terms of use.

### About your company (List of potential company names available) {#about-your-company-list-of-potential-company-names-available}

1. You must choose the Business classification for Merchant to proceed.
2. If your company is not listed in the database, please begin to add the company, and fill out the respective details.
3. Once this is complete, please click "Add My Company".
4. Click on "Complete" which will confirm the registration.

After requesting your account and company, an email will be sent to the Merchant to Activate the Mastercard Connect Account.

## Integration and security {#integration-and-security}

The 3DS Smart Interface uses a secure channel connection with the requestors, that requires a client certificate.

* The requestors must be established as PKI partners. This is required to request and receive the appropriate client certificates to establish connectivity to the 3DS Smart Interface.
* Registration of security officers and key exchanges are managed via the Key Management Portal.
  * The Key Management Portal (KMP) is an application available in Mastercard Connect. KMP provides external customers a self-service portal to request, track manage and renew certificates with Mastercard.

## Certificate exchange -- Key Management Portal {#certificate-exchange--key-management-portal}

The Key Management Portal (KMP) is a new application available in Mastercard Connect. KMP provides you with a Mastercard self-service portal to request and exchange keys and certificates with Mastercard.

The portal provides:

* Guided workflows to create and manage requests for keys and certificates exchange.
* An inventory of all PKI for Business Partners keys and certificates, that have been exchanged between Mastercard and customers using KMP.

### Registration and access to the Key Management Portal {#registration-and-access-to-the-key-management-portal}

* To access KMP, your company must be registered onto Mastercard Connect.
* Once your company has been set up and given a **Company Identifier** (CID), you can register yourself as a user by following the below steps:

#### Procedure {#procedure}

1. Go to [Mastercard Connect](https://www.mastercardconnect.com/mccpblcui/#/public/signin) and then click **Sign Up**.
2. **Sign in** to [Mastercard Connect](https://www.mastercardconnect.com/mccpblcui/#/public/signin).
3. Click **Store** in the top menu.
4. Select the **Apps** tab.
5. Search for **Key Management Portal** in the search bar.
6. On the Key Management Portal card, select **Order**.
7. Select **Security Officer Level 1 access**.
8. Click **Place Order**.

#### Result {#result}

A request for access to KMP was submitted to your Mastercard Connect Security Administrator.

#### Access approval {#access-approval}

The designated Security Administrators within your company must approve your request. Go to the Mastercard Connect homepage and scroll down to get the list of Security Administrators.
Note: At least two security officers must be registered to request certificates.

### Launching the KMP application {#launching-the-kmp-application}

1. **Sign in** to [Mastercard Connect](https://www.mastercardconnect.com/mccpblcui/#/public/signin).

2. Click **My Items**.

3. On the **Key Management Portal** card, click **Open**.

Tip: To add the KMP to your Mastercard Connect Home Page, click the star on the right corner of the Key Management Portal application box

### Adding your certificate management group email {#adding-your-certificate-management-group-email}

Your Certificate Management Group email is an alternative means of communication that the Mastercard Key Management Delivery team will use for crucial communication with your organization in case there is no longer an active user on the Key Management Portal. Avoid entering a personal corporate email address as this entry should not be tied to an individual.

This step is required to complete your registration and begin to submit certificate requests in KMP.

1. Click **My Company**
2. Click on the pencil icon next to **Certificate Management Group Email**
3. Enter your **Certificate Management Group email** and press **Save**

Once the certificate exchange process is completed, you will be notified by the CIS team to test the connectivity.

### Request a certificate {#request-a-certificate}

To request a certificate, please follow the below steps:

1. From the Key Management Portal home page click on **Certificate Requests**
2. Select the appropriate environment **MTF** or **Production**
3. Select Application - **MI Server External Clients -- 3DS**
   * If a certificate profile is required, select **Client**

## Review the sample payload and attributes {#review-the-sample-payload-and-attributes}

Review the sample payload and attributes associated with event notifications.

### Notification payload sample {#notification-payload-sample}

When a search completes, you will receive an event notification. A sample of the payload structure looks like:
* JSON

```JSON
{
 "eventId": "d4acede5-6af2-4176-9c69-c346e1a67095",
 "eventType": "BULK_SEARCH_RESULTS_READY",
 "eventCreatedDate": "2021-09-26T15:38:57.101008Z",
 "data": {
 "bulkRequestId": "f44a24d8-5c9c-408c-86c9-a9de8689eacc"
 }
}
```

Additional event notification structures look like:
* JSON

```JSON
{
"eventId": "d4acede5-6af2-4176-9c69-c346e1a67095",
"eventType": "BULK_SEARCH_CANCELLED",
"eventCreatedDate": "2021-09-26T15:38:57.101008Z",
"data": {
    "bulkRequestId": "f44a24d8-5c9c-408c-86c9-a9de8689eacc",
    "errors": [
        {
            "reasonCode": "SEARCH_ERROR",
            "description": "Search resulted in an error.  No results available.  Please re-submit"
        }
    ]
}
```

### Attributes {#attributes}

Attributes included in the event notification are:

|       Name       |                                                       Description                                                       | Required |  Type  |
|------------------|-------------------------------------------------------------------------------------------------------------------------|----------|--------|
| eventId          | System generated Identifier for the notification event.                                                                 | Yes      | string |
| eventType        | The event that generated the notification. Search generates notifications when the bulk search is completed.            | Yes      | string |
| eventCreatedDate | Date the was event created.                                                                                             | No       | string |
| data             | Notification details for the event.                                                                                     | Yes      | object |
| bulkRequestId    | System generated Identifier for a bulk search request. Using the Id, you can retrieve your bulk search request results. | Yes      | string |