Webhooks

Os webhooks permitem que o Melhor Envio se comunique com seus parceiros integrados, enviando notificações de eventos. Essa tecnologia consiste em um método simples para facilitar que uma plataforma forneça informações em tempo real para outras.

O cadastro de endpoint de webhooks é vinculado com o aplicativo do parceiro, por isso apenas aplicativos integrados podem receber notificações de webhooks.

Por meio do serviços de webhooks o Melhor Envio notifica as atualizações de status das etiquetas geradas. Toda atualização do ciclo de vida de uma etiqueta será enviada para o endpoint cadastrado no aplicativo.

❗️
Para que o webhook do Melhor Envio funcione, as etiquetas precisam ser geradas usando o mesmo aplicativo onde o webhook está configurado. Etiquetas criadas pelo site ou por outro aplicativo, mesmo que na mesma conta, não serão atendidas pelo webhook.

Como garantir a autenticidade das requisições?

Para garantir a autenticidade das requisições, as requisições enviadas pelo Melhor Envio possuem um cabeçalho denominado X-ME-Signature, que se trata de uma assinatura gerada com o algoritmo HMAC-SHA256, utilizando o corpo da requisição como mensagem e o próprio secret do aplicativo como chave criptográfica. Dessa forma, o parceiro pode realizar a verificação desse hash do lado da sua plataforma gerando o hash utilizando o mesmo algoritmo e comparando com o hash enviado na requisição de webhook , caso o hash enviado no cabeçalho for idêntico ao hash gerado pelo parceiro, a requisição foi validada com sucesso.

Retentativas de disparo

Caso a requisição enviada para o endpoint cadastrado pelo parceiro não retorne sucesso na entrega da informação ou não responda após um timeout de 6 segundos será feita uma nova tentativa de envio após um intervalo de 15 minutos.
Serão realizadas 5 tentativas de envio. Após todas as tentativas falharem, essa notificação será descartada.

Como cadastrar um endpoint para receber as atualizações?

Para receber as atualizações, basta acessar a aba “Integrações” → “Área Dev.”, selecionar seu aplicativo e clicar no botão “Novo Webhook”. No modal aberto, informe um endereço de rota pública para onde o Melhor Envio irá realizar as atualizações das informações das etiquetas.

Passo a passo:

Acessar a plataforma do Melhor Envio;
No menu lateral à esquerda, acessar “Integrações” > “Área Dev,”;
No tópico “Seus aplicativos”, encontre a integração na qual você deseja cadastrar a URL para receber os retornos do Webhook. Caso não tenha criado um aplicativo ainda, não será possível receber as notificações do webhook;
Clique no botão “Novo Webhook”;
No modal que será aberto na tela, preencha o campo URL com a página na qual você receberá a atualização do webhook. (Atualmente temos apenas o evento de atualização referente a etiqueta disponível). Exemplo: https://www.plataforma.com.br/webhook-me
Caso já tenha cadastrado um webhook, é possível editá-lo ou removê-lo.

🚧
Eventos de etiqueta
Atualmente existe basicamente um tipo de evento para cada troca de status do ciclo
de vida de uma etiqueta, além do evento de etiqueta criada. Todos os eventos de
etiqueta possuem o prefixo “order.” No ambiente sandbox, a cada 15 minutos a etiqueta muda de status automaticamente até que seja entregue.

order.created: Disparado quando uma etiqueta é criada

order.pending: Disparado quando uma etiqueta é retornada para o carrinho

order.released: Disparado quando uma etiqueta é paga

order.generated: Disparado quando uma etiqueta é gerada

order.received: Disparado quando a encomenda da etiqueta é recebida em um ponto de distribuição Pegaki

order.posted: Disparado quando a encomenda da etiqueta é postada

order.delivered: Disparado quando a encomenda da etiqueta é entregue

order.cancelled: Disparado quando uma etiqueta é cancelada

order.undelivered: Disparado quando a encomenda da etiqueta não pôde ser entregue

order.paused: Disparado quando a entrega é interrompida e é necessária uma ação do destinatário

order.suspended: Disparado quando a encomenda de uma etiqueta é suspensa

📘
A depender da transportadora, o fornecimento do parâmetro “tracking” poderá demorar até 1 dia útil após a postagem do envio.

Método da requisição: POST

Cabeçalho:

{
  
"user-agent": "Melhor Envio Webhooks/1.0",
"accept": "application/json, text/plain, */*",
"accept-encoding": "gzip, compress, deflate, br",
"x-me-signature": "eW/6UEmwJ7vH13kMsrhjMVzek3Yg0Oa5TDsUSeLVFoM=",
"content-type": "application/json",
  
}

Corpo:
Todos os eventos de etiqueta possuem o formato de corpo abaixo:

{
    "event": "order.posted",
    "data": {
        "id": "0000aaaa-aa00-00aa-aa00-000000aaaaaa",
        "protocol": "ORD-2024XXXXXXXXXX",
        "status": "posted",
        "tracking": null,
        "self_tracking": null,
        "user_id": "0000111",
        "tags": [
            {
                "tag": "tag1",
                "url": "www.url1.com"
            }
        ],
        "created_at": "2024-03-29T23:49:26+00:00",
        "paid_at": null,
        "generated_at": null,
        "posted_at": "2024-03-29T23:55:00+00:00",
        "delivered_at": null,
        "canceled_at": null,
        "expired_at": null,
        "tracking_url": "https: //www.melhorrastreio.com.br/rastreio/XXXXXXXXX"
    }
}