Webhooks

Os webhooks permitem que o Melhor Envio se comunique com seus parceiros integrados, enviando algumas 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.

Todo parceiro integrado do Melhor Envio que possui um aplicativo criado na plataforma poderá ter o serviço disponibilizado.

O cadastro de endpoint de webhooks é vinculado com o aplicativo do parceiro, por esse motivo que apenas integrações com aplicativos podem receber notificações de webhooks.

Atualmente, 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.

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 na opção de webhooks. No modal aberto, deve ser informado o endpoint, o endereço da plataforma para onde o Melhor Envio irá
realizar o envio das informações através de uma requisição POST, lembrando que esta rota deve ser pública.

Passo a passo:

1. Acessar a plataforma do Melhor Envio.
2. No menu lateral à esquerda, acessar “Integrações” > “Área Dev,”
3. 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.
4. Clique no botão “Novo Webhook”.
5. 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://wwww.plataforma.com.br/webhook-me
6. Caso já tenha cadastrado um webhook e queira realizar uma edição ou excluir o webhook. Após ter um webhook vinculado a uma aplicação, é 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.”

• 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

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"
    }
}