Webhooks

The Mercado Eletrônico E-Procurement platform provides webhooks so you can be notified about events that occur on the platform.

---

Webhooks are a technology for transmitting real-time notifications between two software systems.
All matters related to logs (continuous record with date and time of the event), key generation, and management of events notified via our APIs' webhooks are handled in the Partner's Portal.

With webhooks, you can be notified about events that occur within E-Procurement of ME, whether you are a buyer or a supplier, for example:

• Order received by the supplier;
• Request approved;
• Pre-order approved;
• Service record approved;
• Results of integrations with all our public APIs. These results can be successfully created entities with their generated IDs or integration errors.

Registering Webhooks

Prerequisite: If you do not yet have access to the Partner's Portal, visit the Credentials page.

1. To register webhooks, go to Partner's Portal > Webhooks.

2. Click Create new and choose the event you would like to receive alerts for.
3. Under Topic, there are some predefined events, for example:
   • Notify when an order has been received by a supplier, or when a request has been approved in the portal.
   • In addition to these events, the user can choose to be notified of all integration results from the portal.
4. Give a name to the event you want to be notified about.
5. In the Callback Url field, add the address of your API where you want to be notified and click Save, as shown in the following screen.

Viewing Sent Notifications

In this example, we will show a notification of Order Created sent through the Event Log page.

We will highlight the main fields of the event divided into the following sections: request details (1), headers (2), and payload (3).

1 - Request Details

Field	Description
Endpoint	Address of your API provided in the Callback Url field when you registered the webhook in Partner's Portal.
Delivery Date	Date and time of the request.
Status	Receipt Status

2 - Headers

Field	Description
X-ME-ATTEMPT	Information on which attempt the request is based on.
X-ME-TOPIC	Topic selected in Partner's Portal corresponding to the event to be notified.
X-ME-EVENT-ID	Internal identifier of the event on the platform.
X-ME-EVENT-KEY	Business identifier of the event on the platform. (In many cases it might be the Correlation Id)
X-ME-WEBHOOK-ID	Internal identifier of the webhook that generated the event.
X-ME-WEBHOOK-SIGNATURE	Signature of the message payload using the verification token. For more information, see Webhook Authentication.

3 - Payload

This section contains a json with the description of the generated event:

Field	Description
topic	Topic selected in Partner's Portal corresponding to the event to be notified.
data	Payload of the event generated by the platform. The properties presented here are dynamic and based on the generated event.
For more information on events and examples of payload, see Overview.

Webhook Authentication

Mercado Eletrônico uses a hash-based message authentication algorithm (HMAC) with SHA-256 to generate signatures. To avoid possible downgrade attacks, it's important to discard any message that does not match a valid signature.

In Partner's Portal > Webhooks > Authentication you can generate your verification token.

❗️ Warning

The provided token will be used as a key in generating the signature. It is important to ensure that this token is kept secret and properly protected, as it is essential for verifying the authenticity of received messages. Keep the token in a secure location and do not share it with unauthorized third parties.

Verifying Signatures

Step 1 - Extract the X-ME-WEBHOOK-SIGNATURE Header

In this step, you need to store the hash value received in the request header. This will allow you to later compare this value with the calculated hash to verify the integrity of the received message.

Step 2 - Determine the Expected Signature

In this step, you need to calculate the HMAC SHA256 of the request payload using the "Verification Token" as the key. HMAC SHA256 is a secure hash algorithm that ensures data integrity.

Step 3 - Compare the Signatures

In this step, you need to compare the received signature with the generated signature. If the signatures are different, you should reject the request as this indicates that the data integrity may have been compromised.

Example Written in C#

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using System.Security.Cryptography;
using System.Text;

var app = WebApplication.Create();

const string SharedSecret = "YOUR_VERIFICATION_TOKEN_HERE";

app.MapPost("/webhook", async (HttpContext context) =>
{
    string receivedSignature = context.Request.Headers["X-ME-WEBHOOK-SIGNATURE"];
    string webhookContent = await context.Request.ReadAsStringAsync();

    if (!VerifyWebhookSignature(webhookContent, receivedSignature))
    {
        await context.Response.WriteAsync("Invalid signature. The webhook may have been tampered with!");
        context.Response.StatusCode = 400;
        return;
    }

    // Signature is valid, process the webhook
    await context.Response.WriteAsync("Webhook received successfully!");
});

bool VerifyWebhookSignature(string content, string receivedSignature)
{
    using HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes(SharedSecret));
    byte[] signatureBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(content));
    string calculatedSignature = Convert.ToBase64String(signatureBytes);
    return calculatedSignature.Equals(receivedSignature);
}

app.Run();

ME Webhook IP Addresses

The IP addresses from which webhook notifications may come are:

• 20.102.37.227
• 191.232.73.226
• 164.152.52.63

Depending on how your integration operates, you may need to add these to a whitelist.

Retry Logic

If our service encounters issues delivering your notifications, we will attempt to resend them 13 more times, as described below:

• 1st attempt after 5 minutes.
• 2nd attempt after 10 minutes.
• 3rd attempt after 20 minutes.
• 4th attempt after 40 minutes.
• 5th attempt after 1 hour.
• 6th attempt after 2 hours.
• Once per day for up to 7 days.

The final attempt will be made 7 days after the initial attempt.

Possible issues with sending notifications:

• If your callback endpoint takes longer than 10 seconds to respond.
• If the response from your callback endpoint has a status code other than 2xx.

After a failure, notifications are queued for retry.
If a notification fails to be resent for 7 days, it will be marked as "exhausted" and will no longer be reprocessed.

Event Handling

Proper handling of webhook events is crucial to ensure that your integration's business logic works as expected.

Handling Duplicate Events

Webhook endpoints may occasionally receive the same event more than once. We recommend protecting yourself against receiving duplicate events by making your event processing idempotent.

One way to do this is to log events that have already been processed and then, based on this log, avoid processing them again.

The X-ME-EVENT-ID field is a unique identifier found in the header of each event and can help with this control:

For information on the Webhooks APIs, see API Reference > Webhooks API.