Webhooks

A plataforma E-Procurement do Mercado Eletrônico oferece webhooks para que vocês possam ser notificados sobre os eventos que ocorrem na plataforma.

Os webhooks são uma tecnologia para transmitir notificações em tempo real entre dois softwares.
Todas as questões relacionadas a logs (registro contínuo com data e hora do evento), geração de chaves e gerenciamento de eventos notificados via webhooks das nossas APIs são feitos no Partner's Portal.

Com os webhooks, você poderá ser notificado sobre eventos que acontecem dentro do E-Procurement do ME, seja você cliente comprador ou fornecedor, por exemplo:

Pedido recebido pelo fornecedor;
Requisição aprovada;
Pré-pedido aprovado;
Folha de registro de serviço aprovada;
Resultados das integrações com todas as nossas APIs públicas. Estes resultados podem ser entidades criadas com sucesso com seus IDs gerados ou erros de integração.

Cadastro de webhooks

❗️ Pré-requisito:
Se você ainda não tem acesso ao Partner's Portal, acesse a página de Credenciais.

Para cadastrar os Webhooks acesse Partner's Portal > Webhooks.

Credenciais:

webhooks-aba-credenciais

A seguir são apresentadas as diferenças entre Basic Auth e OAuth2 que são os tipos de credenciais permitidas:

Basic Auth:

Com o Basic Auth o sistema envia usuário e senha (ou ID + Secret) codificados em Base64 no header de uma requisição.

Exemplo de header em uma requisição:

Authorization: Basic dXN1YXJpbzpwYXNzd29yZA==

Uso típico:
- Integrações simples;
- Ambientes legados;
- Quando o provedor não oferece OAuth2.
Limitações:
- Menos seguro: as credenciais ficam estáticas e precisam ser protegidas com muito cuidado.
- Não há expiração automática: se vazar, pode ser usado indefinidamente.

OAuth2:

O OAuth2 usa um fluxo de concessão de token. Primeiro, o sistema obtém um access_token (com base em client_id, client_secret, grant type etc.). No caso do ME é com base no cliente_secret. Depois, cada requisição usa um token parecido com este no header:

Authorization: Bearer eyJhbGciOi...

Uso típico:
- Integrações modernas;
- APIs que seguem OpenID Connect, Keycloak, Auth0, Azure AD, etc.
Vantagens:
- Tokens expiram automaticamente (menor risco em caso de vazamento);
- Suporta escopos (permissões granulares);
- Muito mais seguro e recomendado para ambientes corporativos/B2B.

Comparação Rápida entre Basic Auth e OAuth2

Item	Basic Auth	OAuth2
Forma	Usuário + senha fixos	Tokens temporários
Segurança	Baixa (estático)	Alta (tokens expiram)
Complexidade	Simples	Mais complexo de configurar
Recomendado para	Sistemas legados, integrações internas simples	Integrações modernas, APIs expostas, ambientes corporativos

Como preencher uma credencial do tipo OAuth2?

webhooks-editar-credenciais

Preencha os campos da tela de credenciais do tipo OAuth2 da seguinte forma:

Nome: Rótulo interno para identificar a credencial. Use um nome claro para saber qual integração está usando, ex.: keycloak, me-app, auth-mercadoeletronico;
Tipo: Define o protocolo de autenticação. Selecione OAuth2;
Serviço de Autorização: URL do Authorization Server responsável por emitir o token. Informe a URL de login do IdP (Provedor de Identidade, ex.: Keycloak, Auth0, Azure AD). Geralmente termina com /auth/realms/{realm}/protocol/openid-connect/token;
ID do Cliente (Client ID): É o identificador público da aplicação registrada no IdP. Copie o Client ID cadastrado no Keycloak (ou outro IdP). Exemplo: me-webhooks-integracao.
Secret do Cliente (Client Secret): É a Chave privada associada ao Client ID. Cole o segredo gerado no IdP.
Tipo de Concessão (Grant Type): Define o fluxo OAuth2 utilizado para obter o token. Como preencher:
- client_credentials → quando a autenticação é de máquina para máquina (APIs, integrações backend).
- authorization_code → quando envolve login de usuário interativo.
Escopo (Scope): Define os privilégios associados ao token. Informe os escopos que a aplicação precisa. Ex.: profile, openid, email, ou um escopo customizado definido no IdP.
Tipo de Solicitação de Token: é a forma como os parâmetros são enviados na requisição de token. Como preencher:
- URL Encoded Form → mais comum (enviado via application/x-www-form-urlencoded).
- Pode haver também JSON Body, dependendo do IdP.
Customização OAuth2 (Add override): Permite sobrescrever parâmetros avançados. Use se precisar enviar campos adicionais como: audience, resource, realm etc. Caso não precise, pode deixar em branco.
Botão Testar → Realiza a chamada de autenticação com os dados preenchidos para validar se o token é emitido corretamente.

Depois de preencher todos estes campos, clique em Salvar e a sua credencial aparecerá na lista de credenciais cadastradas.

Inscrições:

Clique na aba de Inscrições.
Clique em Criar Novo e escolha o evento sobre o qual você gostaria de receber alertas.
Em Tópico, existem alguns eventos já predefinidos, por exemplo:
- Notificar quando um pedido foi recebido por um fornecedor, ou quando uma requisição foi aprovada no portal.
- Além desses eventos, o usuário pode escolher ser notificado de todos os resultados de integração do portal.
Dê um nome para o evento que gostaria de ser notificado.
No campo Callback Url, adicione o endereço da sua API no qual você quer ser notificado.
Selecione a Credencial criada na etapa anterior e clique em Salvar.

Visualização das notificações enviadas

Neste exemplo mostraremos uma notificação de Order Created enviada através da página de Event Log (Registro de Eventos).

A seguir destacaremos os principais campos do evento divididos pelas seções: detalhes da requisição (1), cabeçalho (2) e conteúdo (3).

1 - Detalhes da Requisição

Campo	Descrição
Endpoint	Endereço da sua API que foi informado no campo Callback Url quando você cadastrou o webhook no Partner's Portal.
Delivery Date	Data e hora da requisição.
Status	Status de Recebimento

2 - Headers

Campo	Descrição
X-ME-ATTEMPT	Informação de qual tentativa a requisição se baseia.
X-ME-TOPIC	Tópico selecionado no Partner's Portal correspondente ao evento a ser notificado.
X-ME-EVENT-ID	Identificador interno do evento na plataforma.
X-ME-EVENT-KEY	Identificador de negócio do evento na plataforma. (Em muitos casos poderá ser o Correlation Id)
X-ME-WEBHOOK-ID	Identificador interno do webhook que gerou o evento.
X-ME-WEBHOOK-SIGNATURE	Assinatura do payload da mensagem utilizando o verification token. Para mais informações, acesse Autenticação dos webhooks.

3 - Payload

Nesta seção temos um json com a descrição do evento gerado:

Campo	Descrição
`topic`	Tópico selecionado no Partner's Portal correspondente ao evento a ser notificado.
`data`	Payload do evento gerado pela plataforma. As propriedades apresentadas aqui são dinâmicas e com base no evento gerado.
Para mais informações sobre eventos e exemplos de payload acesse Overview.

Autenticação dos webhooks

O Mercado Eletrônico utiliza um algoritmo de autenticação de mensagem baseado em hash (HMAC) com SHA-256 para gerar assinaturas. A fim de evitar possíveis ataques de downgrade, é importante descartar qualquer mensagem que não corresponda a uma assinatura válida.

Em Partner's Portal > Webhooks > Authentication você pode gerar o seu verification token.

❗️ Cuidado
O token fornecido será utilizado como chave na geração da assinatura. É importante garantir que esse token seja mantido em segredo e protegido adequadamente, pois ele é essencial para a verificação da autenticidade das mensagens recebidas. Mantenha o token em um local seguro e não o compartilhe com terceiros não autorizados.

Verificar assinaturas

Etapa 1 - Extraia o header X-ME-WEBHOOK-SIGNATURE

Nesta etapa, é necessário armazenar o valor do hash recebido no header da requisição. Isso permitirá que você compare posteriormente esse valor com o hash calculado para verificar a integridade da mensagem recebida.

Etapa 2 - Determine a assinatura esperada

Nesta etapa, você precisa calcular o HMAC SHA256 do payload da requisição usando o "Verification Token" como chave. O HMAC SHA256 é um algoritmo de hash seguro que garante a integridade dos dados.

Etapa 3 - Compare as assinaturas.

Nesta etapa, você precisa comparar a assinatura recebida com a assinatura gerada. Se as assinaturas forem diferentes, você deve recusar a requisição, pois isso indica que a integridade dos dados pode ter sido comprometida.

Exemplo escrito em C#

csharp

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

var app = WebApplication.Create();

const string SharedSecret = "SEU_VERIFICATION_TOKEN_AKI";

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("Assinatura inválida. O webhook pode ter sido adulterado!");
        context.Response.StatusCode = 400;
        return;
    }

    // A assinatura é válida, processar o webhook
    await context.Response.WriteAsync("Webhook recebido com sucesso!");
});

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();

Endereços IP de webhook do ME

Os endereços IP de onde as notificações de webhook podem vir são:

20.102.37.227
191.232.73.226
164.152.52.63

Dependendo de como sua integração opera, pode ser necessário adicioná-los a uma lista de permissões.

Lógica de repetições de tentativas de entrega

❗️ Atenção
Cada tentativa de envio ao endpoint é registrada. O campo Status / Tentativa não reflete o resultado da operação no sistema, mas sim o status da tentativa de comunicação com o cliente.

Se o nosso serviço tiver problemas na entrega das suas notificações, tentaremos enviá-las mais 13 vezes, como descrito a seguir:

1ª tentativa depois de 5 minutos.
2ª tentativa depois de 10 minutos.
3ª tentativa depois de 20 minutos.
4ª tentativa depois de 40 minutos.
5ª tentativa depois de 1 hora.
6ª tentativa depois de 2 hora.
Uma vez por dia até 7 dias.

A última tentativa será feita 7 dias após a tentativa inicial.

Possíveis problemas no envio de notificações:

Se o seu endpoint de retorno de chamada (callback endpoint) demorar mais de 10 segundos para responder. Neste caso, a tentativa é considerada falha (Request Timeout).
Se a resposta do seu endpoint de retorno de chamada (callback endpoint) tiver um status code diferente de 2xx.

Depois da falha no envio, as notificações são colocadas em fila de espera para serem processadas novamente.
Se o reenvio de uma notificação falhar por 7 dias, a notificação será marcada como “exhausted” e não será mais reprocessada.

Não é recomendado:

Processar lógica de negócio antes de retornar (pode ultrapassar timeout);
Retornar 4XX ou 5XX por falhas de regra de negócio.

Boas Práticas para o Cliente:

Não processar regra de negócio durante o recebimento. Salvar a mensagem em uma fila e responder 200;
Retornar sempre 200 ou 204 ao receber a notificação;
Evitar retornos 400/403/500, pois implicam nova tentativa pelo sistema;
Implementar verificação de assinatura para validar autenticidade do Webhook usando o header Webhook-Signature.

Diferença entre Sucesso do Evento e Sucesso da Notificação:

O fato de um pedido ser criado com sucesso na plataforma não garante que o cliente foi notificado;
Sucesso de notificação = recebimento do Webhook com resposta HTTP 2XX;
Falha de notificação ≠ falha na operação original.

Tratamento de eventos

O tratamento correto dos eventos de webhook é crucial para garantir que a lógica de negócios da sua integração funciona como esperado.

Tratamento de eventos duplicados

Os endpoints de webhook podem ocasionalmente receber o mesmo evento mais de uma vez. Recomendamos que você se proteja contra o recebimento de eventos duplicados, tornando o seu processamento de eventos idempotente.

Uma forma de fazer isto é registar os eventos que já foram processados, e depois, com base neste registro, não processá-los novamente.

O campo X-ME-EVENT-ID é um identificador único que fica localizado no header de cada evento e pode ajudar a fazer esse controle:

Para informações sobre as APIs dos Webhooks, acesse API Reference > Webhooks API.

Visão Geral

OData feed

Schemas

Excel Custom

Webhooks

Cadastro de webhooks

Credenciais:

Basic Auth:

OAuth2:

Comparação Rápida entre Basic Auth e OAuth2

Como preencher uma credencial do tipo OAuth2?

Inscrições:

Visualização das notificações enviadas

1 - Detalhes da Requisição

2 - Headers

3 - Payload

Autenticação dos webhooks

Verificar assinaturas

Etapa 1 - Extraia o header X-ME-WEBHOOK-SIGNATURE

Etapa 2 - Determine a assinatura esperada

Etapa 3 - Compare as assinaturas.

Exemplo escrito em C#

Endereços IP de webhook do ME

Lógica de repetições de tentativas de entrega

Boas Práticas para o Cliente:

Diferença entre Sucesso do Evento e Sucesso da Notificação:

Tratamento de eventos

Tratamento de eventos duplicados

OData feed

Webhooks ​

Cadastro de webhooks ​

Credenciais: ​

Basic Auth: ​

OAuth2: ​

Comparação Rápida entre Basic Auth e OAuth2 ​

Como preencher uma credencial do tipo OAuth2? ​

Inscrições: ​

Visualização das notificações enviadas ​

1 - Detalhes da Requisição ​

2 - Headers ​

3 - Payload ​

Autenticação dos webhooks ​

Verificar assinaturas ​

Etapa 1 - Extraia o header X-ME-WEBHOOK-SIGNATURE ​

Etapa 2 - Determine a assinatura esperada ​

Etapa 3 - Compare as assinaturas. ​

Exemplo escrito em C# ​

Endereços IP de webhook do ME ​

Lógica de repetições de tentativas de entrega ​

Boas Práticas para o Cliente: ​

Diferença entre Sucesso do Evento e Sucesso da Notificação: ​

Tratamento de eventos ​

Tratamento de eventos duplicados ​

Webhooks

Cadastro de webhooks

Credenciais:

Basic Auth:

OAuth2:

Comparação Rápida entre Basic Auth e OAuth2

Como preencher uma credencial do tipo OAuth2?

Inscrições:

Visualização das notificações enviadas

1 - Detalhes da Requisição

2 - Headers

3 - Payload

Autenticação dos webhooks

Verificar assinaturas

Etapa 1 - Extraia o header X-ME-WEBHOOK-SIGNATURE

Etapa 2 - Determine a assinatura esperada

Etapa 3 - Compare as assinaturas.

Exemplo escrito em C#

Endereços IP de webhook do ME

Lógica de repetições de tentativas de entrega

Boas Práticas para o Cliente:

Diferença entre Sucesso do Evento e Sucesso da Notificação:

Tratamento de eventos

Tratamento de eventos duplicados