# Webhooks
source: https://developer.mastercard.com/open-finance-au/documentation/connect/webhooks/index.md

## Connect Webhooks {#connect-webhooks}

Webhook events are sent during a Connect session as the customer interacts with the application. You can track progress through a session, get information about customer usage, and receive notifications when certain processes are complete.

### Event Body {#event-body}

All events include a wrapper that contains metadata. The event data is within the `payload` key. If you specified custom events via the `webhookData` parameter when [generating a Connect URL](https://developer.mastercard.com/open-finance-au/documentation/connect/generate-2-connect-url-apis/index.md), they will be visible within the `webhookData` key.
* JSON

```JSON
{
  "customerId":"12345678",
  "consumerId":"ed81281fcec7ec557aa7d292a3188b75",
  "eventType":"started",
  "eventId":"1495468585434-0e73d1719173766fe4dfe1a8",
  "payload":{
    "event data will be here"
  },
  "webhookData": {
    "custom event data will be here"
  }
}  
```

### Prevent Spoofing {#prevent-spoofing}

If you're using webhooks for sensitive or critical information, we recommend that you verify the signature of the webhook.

###### Tips for Best Practice: {#tips-for-best-practice}

1. Create a SHA-256 HMAC of the request body using your Partner Secret as the key.
2. Compare it to the signature included on the X-Signature header. If the two are equal then the request is valid, otherwise, it is spoofed.
3. Store the `eventId` and ignore webhooks with an ID that have already been processed to prevent replay attacks.

The X-Signature header gets added to every event sent.

**Here is an example of signature verification in NodeJS:**

```javascript
const crypto = require('crypto');
const partnerSecret = '{{PARTNER_SECRET}}';
router.use('/webhook-handler', (request, res) => {
  const body = request.body;
  const signature = crypto
    .createHmac('sha256', partnerSecret)
    .update(JSON.stringify(body))
    .digest('hex');

  if (request.get('x-signature') !== signature) {
    throw new Error('Spoofing detected, rejecting webhook');
  }
});
```

Tip: If we get a 200 HTTP response from your webhook listener server, the webhook event is registered as a success. For any non-200 HTTP status code (failed event), we will resend the webhook.

Our retry logic will function for 3 days with an exponential back-off, meaning we will try multiple times within the first few minutes followed by a retry every hour for 72 hours. The exact instances of each retry within the first few minutes are as follows: 12ms, 72ms, 432ms, 2592ms, 15552ms, 93312ms.

Once the max retry window is reached, the notification retry will stop.

See [Connect Events List](https://developer.mastercard.com/open-finance-au/documentation/connect/webhooks/webhooks-event-connect/index.md) for details of the Connect webhook events.

## Report Webhooks {#report-webhooks}

When you send a request to one of the endpoints that generates a report, you can specify a URL for your report listener (using the optional `callbackUrl` request parameter), which then receives the report information.

Report events notify you about the progress of a requested report. Events are sent when a report starts, updates, fails, or completes.

### Setting up a Report Listener {#setting-up-a-report-listener}

Here are some basic steps to follow when you want to set up an endpoint to receive webhook events on your server.

1. Add an inbound endpoint to receive webhook events, for example `/reportlistener`.
2. Set the `content type` of the body to match the accept header used in the Generate Report call.
3. Set the security on your endpoint to allow the HTTPS protocol.
4. Test the endpoint locally to simulate external calls to your application. We recommend testing with the URL: <http://ngrok.com>.
5. Process the test request on a separate thread and return an HTTP 200 success response.

#### Example code {#example-code}

**Java**

```java
@PostMapping(value = "/yourCallback", accepts = "application/xml")
```

**Javascript**

```javascript
app.post('/yourCallback', bodyParser.raw({type:'application/json'}), (req, resp) => {};
```

Note: Since report webhooks are sent only one time (with three attempts to retry if it is not successfully recieved), we recommend processing the webhook data on a different thread as soon as it is received.

See [Reports Events List](https://developer.mastercard.com/open-finance-au/documentation/connect/webhooks/webhooks-event-report/index.md) for details of the report webhook events.

## Custom Webhooks {#custom-webhooks}

There are two different objects you can use to receive information while the customer is interacting in a Connect or joint borrower session on a mobile app or web pages.

* [webhookData Object](https://developer.mastercard.com/open-finance-au/documentation/connect/webhooks/index.md#webhookdata-object)
* [webhookHeaders Object](https://developer.mastercard.com/open-finance-au/documentation/connect/webhooks/index.md#webhookheaders-object)

### webhookData Object {#webhookdata-object}

If you pass the `webhookData` object in the [Generate Connect URL APIs](https://developer.mastercard.com/open-finance-au/documentation/connect/generate-2-connect-url-apis/index.md), you will receive the object back in the body for all other Connect event types.

**Example:** Pass the `webhookData` object in a Generate Connect URL call to receive the `started` event notification.

```JSON
"webhookData": {
  "unquiqueCustomerId": "123456789",
  "uniqueRequestId": "234567890"
}
```

```JSON
{
  "customerId": "1463546",
  "eventType": "adding",
  "eventId": "1704384256449-196c11028016c7976922ff2a",
  "payload": {
    "institutionId": "200003",
    "oauth": true
  },
  "webhookData": {
    "unquiqueCustomerId": "123456789",
    "uniqueRequestId": "234567890"
  }
}
```

### webhookHeaders Object {#webhookheaders-object}

Passing the `webhookHeaders` object provides similar custom return behavior for every webhook event. However, it returns the results in the header instead of the body of the event.

```json
"webhookHeaders": {
  "webhookServerKey": "sadf67ewrkh",
  "webhookCustomerSignature": "91l;kj234924987lj"
}
```

```json
{
  "customerId": "1463546",
  "eventType": "adding",
  "eventId": "1704384256449-196c11028016c7976922ff2a",
  "payload": {
    "institutionId": "200003",
    "oauth": true
  },
  "webhookData": {
    "unquiqueCustomerId": "123456789",
    "uniqueRequestId": "234567890"
  },
  "webhookHeaders": {
    "webhookServerKey": "sadf67ewrkh",
    "webhookCustomerSignature": "91l;kj234924987lj"
  }
}
```

## Allowed IP Addresses {#allowed-ip-addresses}

To ensure both Connect and consent webhook notifications reach your webhook listener server, you must add the following Mastercard IP addresses to your firewall's allowlist:

    54.66.101.2
    13.238.109.236
    52.62.188.205