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.
- Clique em Create new e escolha o evento sobre o qual você gostaria de receber alertas.
- Em Topic, 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 e clique em Save, conforme tela a seguir.
Visualização das notificações enviadas
Neste exemplo mostraremos uma notificação de Order Created enviada através da página de Event Log.
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 | Informacao de qual tentativa a requisicao 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 negocio do evento na plataforma. (Em muitos casos podera 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#
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
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.
- 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.
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.