Pular para o conteúdo principal

O que são e como funcionam os Webhooks?

Webhook é uma forma do seu sistema receber informações do Delivery Direto e são passadas quando um evento acontece na Plataforma do Delivery Direto.

Sempre que ocorre um evento importante, nós disparamos uma notificação para seu servidor. Essas notificações são chamadas de webhooks. É possível configurar varios endpoints e escolher quais eventos serão disparados.

info

Os Webhooks estão disponíveis apenas na Admin API.

Eventos​

Os eventos webhooks disponíveis na Admin API são as seguintes:

  • ORDER_PLACED: disparado quando um cliente cria um pedido na loja.
  • ORDER_STATUS_CHANGED: disparado quando um pedido tem o status alterado, tanto pelo operador da loja quanto pela API.
  • ORDER_EDITED: disparado quando um pedido é editado pelo operador da lojas.

Como eu recebo esses eventos?​

Você deve implementar um endpoint público em seu sistema para que o Delivery Direto posso enviar a notificação do evento.

info

Todas as requisições geradas a partir de webhooks são efetuadas com o método POST, com o conteúdo no corpo (body) da requisição no formato JSON.

tip

Você pode usar o RequestBin para facilmente inspecionar e debugar os webhooks que você recebe.

Configurando seus Webhooks​

O primeira passo para interagir com nossos webhooks é cadastrar a URL que receberá as suas requisições. A operação à qual você deseja associar determinada URL é passada no corpo da requisição. O webhook é configurado para cada loja, e não para cada integração, então se seu sistema opera para múltiplas lojas no Delivery Direto, o cadastro dos webhooks deve ser feito para cada uma delas.

É possível também ativar ou inativar um webhook por este mesmo endpoint da nossa API.

Além disso, é possível apagar um webhook cadastrado, caso não se deseje mais utilizar um webhook específico.

Veja mais detalhes na API Reference na sessão Webhooks.

Assim que um webhook é configurado, passamos a enviar requisições para a URL cadastrada toda vez que a operação atrelada ao webhook ocorre no Delivery Direto.

Retornos dos Webhooks​

Todas as requisições geradas a partir de webhooks são efetuadas com o método POST, com o conteúdo no corpo (body) da requisição no formato JSON, incluindo os seguintes headers:

Headers​

Headers enviados na chamada do Webhook
Content-Type: application/json
X-DeliveryDireto-ID: <X-DeliveryDireto-ID>
X-DeliveryDireto-Signature: <X-DeliveryDireto-Signature>

Onde:

  • X-DeliveryDireto-ID: é o identificador da loja que ocorreu o evento.
  • X-DeliveryDireto-Signature: é a assinatura da requisição para validar a autenticidade da requisição.
info

O X-DeliveryDireto-Signature é composto pelo Hash HMAC SHA256 do corpo da requisição (body) onde a chave de criptografia é sua CLIENT_SECRET.

Payload (body)​

Payload de uma chamada do Webhook
{
    "ordersId": ..., 
    "storesId": ..., 
    "eventType": ..., 
    "order": ..., 
    "orderStatus": ...
}

Os webhooks de recebimento de um pedido por uma loja (ORDER_PLACED) e de edição de um pedido em uma loja (ORDER_EDITED) retornam os dados completos do pedido no campo order no paylod (não é retornado o campo orderStatus nesses casos).

Exemplo do Body de uma chamada Webhook do tipo ORDER_PLACED
{
    "ordersId": 123, 
    "storesId": 123, 
    "eventType": "ORDER_PLACED", 
    "order": {
        ....
    }
}

Já o webhook de alteração do status de um pedido (ORDER_STATUS_CHANGED) retorna apenas o campo orderStatus do pedido.

Exemplo do Body de uma chamada Webhook do tipo ORDER_STATUS_CHANGED
{
    "ordersId": 123, 
    "storesId": 123, 
    "eventType": "ORDER_STATUS_CHANGED", 
    "orderStatus": "APPROVED"
}

Retentativas​

Em caso de falha no envio, 3 retentativas são feitas:

  • A primeira a um minuto da tentativa original.
  • A segunda a dois minutos da primeira retentativa.
  • A terceira e última, cinco minutos após a segunda retentativa.

Caso o envio não seja feito com sucesso em nenhuma dessas tentativas, este envio específico é cancelado, e fica sinalizado com um status de erro.

info

Caso a URL cadastrada retorne o HTTP Status diferente de 200 (OK), é considerado uma falha.

É possível também conferir os status dos envios dos webhooks, juntamente com os dados que seriam enviados com os mesmos (presentes no campo payload do retorno do endpoint).

Caso queira testar o funcionamento de algum webhook, é possível também forçar uma nova chamada de um determinado webhook.