Configure notifications

Below is a step-by-step guide to receive notifications in Wallet Connect integrations. Once configured, Webhook notifications will be sent whenever any update occurs on the reported topics, including creation and update of orders, transaction processing, and linking events.

1. Access Your integrations and select the application created by the team responsible for your Wallet Connect integration, for which you want to activate notifications.

2. In the left menu, select Webhooks > Configure notifications.

3. Select the Production mode tab and provide an HTTPS URL to receive notifications with your productive integration.

4. Select the events to receive notifications:

   • Order (Mercado Pago): to receive payment notifications made with the Orders API.
   • Wallet Connect: to receive notifications for linking events (confirmation and cancellation).

5. Finally, click Save configuration. This will generate an exclusive secret key for the application, which will allow validating the authenticity of received notifications, ensuring they were sent by Mercado Pago. Keep in mind that this generated key has no expiration date and periodic renewal is not mandatory, although it is recommended. To do so, just click the Reset button.

To ensure that notifications are configured correctly, it is necessary to simulate their reception. To do this, follow the step-by-step below.

1. After configuring the URL and events, click Save configuration.
2. Then, click Simulate to test whether the indicated URL is receiving notifications correctly.
3. In the simulation screen, select the URL to be tested.
4. Next, select the event type and enter the identification that will be sent in the notification body (Data ID).
5. Finally, click Send test to verify the request, the response provided by the server, and the event description.

Validating the origin of a notification is essential to ensure the security and authenticity of the information received. This process helps prevent fraud and ensures that only legitimate notifications are processed.

Mercado Pago will send your server a notification similar to the example below for an order topic alert. This example includes the complete notification, containing the query params, the body, and the header of the notification.

• Query params: Query parameters that accompany the URL. In the example, these are data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3 and type=order.
• Body: The notification body contains detailed information about the event, such as action, api_version, application_id, date_created, id, live_mode, type, user_id, and data.
• Header: The header contains important metadata, including the notification's secret signature x-signature.

plain
POST /test?data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3&type=order HTTP/1.1
Host: prueba.requestcatcher.com
Accept: */*
Content-Type: application/json
X-Request-Id: 2066ca19-c6f1-498a-be75-1923005edd06
X-Signature: ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b
{"action":"order.action_required","api_version":"v1","application_id":"76506430185983","date_created":"2021-11-01T02:02:02Z","id":"123456","live_mode":false,"type":"order","user_id":2025701502,"data":{"id":"ORD01JQ4S4KY8HWQ6NA5PXB65B3D3"}}

From the received Webhook notification, you can validate the authenticity of its origin. Mercado Pago will always include the secret key in the Webhook notifications received, which will allow validating their authenticity. This key will be sent in the x-signature header.

To confirm the validation, it is necessary to extract the key contained in the header and compare it with the key provided for your application in Your integrations. To do this, follow the step-by-step below.

1. To extract the timestamp (ts) and key (v1) from the x-signature header, split the header content by the "," character. The value for the ts prefix is the notification timestamp (in milliseconds) and v1 is the encrypted key.
2. Using the template below, replace the parameters with the data received in your notification.

plain
id:[data.id_url];request-id:[x-request-id_header];ts:[ts_header];

3. In Your integrations, select the integrated application, click Webhooks > Configure notification and reveal the generated secret key.
4. Generate the counter-key for validation. To do this, calculate an HMAC with the SHA256 hash function in hexadecimal base, using the secret signature as the key and the template with the values as the message.

$cyphedSignature = hash_hmac('sha256', $data, $key);

const crypto = require('crypto');
const cyphedSignature = crypto
    .createHmac('sha256', secret)
    .update(signatureTemplateParsed)
    .digest('hex');

String cyphedSignature = new HmacUtils("HmacSHA256", secret).hmacHex(signedTemplate);

import hashlib, hmac, binascii

cyphedSignature = binascii.hexlify(hmac_sha256(secret.encode(), signedTemplate.encode()))

5. Finally, compare the generated key with the key extracted from the header, making sure they match exactly.

See complete code examples below:

<?php
$xSignature = $_SERVER['HTTP_X_SIGNATURE'];
$xRequestId = $_SERVER['HTTP_X_REQUEST_ID'];
$queryParams = $_GET;
$dataID = isset($queryParams['data.id']) ? $queryParams['data.id'] : '';
$parts = explode(',', $xSignature);
$ts = null;
$hash = null;
foreach ($parts as $part) {
    $keyValue = explode('=', $part, 2);
    if (count($keyValue) == 2) {
        $key = trim($keyValue[0]);
        $value = trim($keyValue[1]);
        if ($key === "ts") {
            $ts = $value;
        } elseif ($key === "v1") {
            $hash = $value;
        }
    }
}
$secret = "your_secret_key_here";
$manifest = "id:$dataID;request-id:$xRequestId;ts:$ts;";
$sha = hash_hmac('sha256', $manifest, $secret);
if ($sha === $hash) {
    echo "HMAC verification passed";
} else {
    echo "HMAC verification failed";
}
?>

const xSignature = headers['x-signature'];
const xRequestId = headers['x-request-id'];
const urlParams = new URLSearchParams(window.location.search);
const dataID = urlParams.get('data.id');
const parts = xSignature.split(',');
let ts;
let hash;
parts.forEach(part => {
    const [key, value] = part.split('=');
    if (key && value) {
        const trimmedKey = key.trim();
        const trimmedValue = value.trim();
        if (trimmedKey === 'ts') {
            ts = trimmedValue;
        } else if (trimmedKey === 'v1') {
            hash = trimmedValue;
        }
    }
});
const secret = 'your_secret_key_here';
const manifest = `id:${dataID};request-id:${xRequestId};ts:${ts};`;
const hmac = crypto.createHmac('sha256', secret);
hmac.update(manifest);
const sha = hmac.digest('hex');
if (sha === hash) {
    console.log("HMAC verification passed");
} else {
    console.log("HMAC verification failed");
}

import hashlib
import hmac
import urllib.parse

xSignature = request.headers.get("x-signature")
xRequestId = request.headers.get("x-request-id")
queryParams = urllib.parse.parse_qs(request.url.query)
dataID = queryParams.get("data.id", [""])[0]
parts = xSignature.split(",")
ts = None
hash = None
for part in parts:
    keyValue = part.split("=", 1)
    if len(keyValue) == 2:
        key = keyValue[0].strip()
        value = keyValue[1].strip()
        if key == "ts":
            ts = value
        elif key == "v1":
            hash = value
secret = "your_secret_key_here"
manifest = f"id:{dataID};request-id:{xRequestId};ts:{ts};"
hmac_obj = hmac.new(secret.encode(), msg=manifest.encode(), digestmod=hashlib.sha256)
sha = hmac_obj.hexdigest()
if sha == hash:
    print("HMAC verification passed")
else:
    print("HMAC verification failed")

When you receive a notification on your platform, Mercado Pago expects a response to validate that the reception was correct. To do this, you must return an HTTP STATUS 200 (OK) or 201 (CREATED).

The waiting time for this confirmation will be 22 seconds. If this confirmation is not sent, the system will understand that the notification was not received and will make a new send attempt every 15 minutes, until it receives the response.

After responding to the notification and confirming its receipt, you can obtain all the information about the notified resource by sending a request to the endpoint /v1/orders/{id}GET.

Learn about the linking and payment events that trigger Webhook notifications and see examples of the data sent in each case.

json
{
  "id": "22abcd1235ed497f945f755fcaba3c6c",
  "type": "wallet_connect",
  "entity": "agreement",
  "action": "status.updated",
  "date": "2021-09-30T23:24:44Z",
  "model_version": 1,
  "version": 0,
  "data": {
    "id": "22abcd1235ed497f945f755fcaba3c6c",
    "status": "confirmed_by_user"
  }
}

json
{
  "id": "22abcd1235ed497f945f755fcaba3c6c",
  "type": "wallet_connect",
  "entity": "agreement",
  "action": "status.updated",
  "date": "2021-09-30T23:24:44Z",
  "model_version": 1,
  "version": 0,
  "data": {
    "id": "22abcd1235ed497f945f755fcaba3c6c",
    "status": "canceled"
  }
}