Pular para o conteúdo principal

Como criar um receptor de Webhook?

Neste guia, você aprenderá como usar o Node.js para criar um receptor de webhook para seu aplicativo. Esse mesmo conceito pode ser aplicado à outras linguagens de programação.

dica

Clique aqui para saber mais sobre Webhooks

Configurando o projeto​

Crie um novo diretório para o seu projeto e navegue até ele:

mkdir webhook-receiver
cd webhook-receiver

Inicialize um novo projeto e instale as dependências necessárias:

Instalando dependências necessárias para o exemplo
npm init -y
npm install express crypto body-parser

Configurando o receptor dos eventos vindo via Webhook​

Crie um novo arquivo chamado index.js no diretório do seu projeto e adicione o seguinte código:

Exemplo de código para o servidor que irá receber os eventos Webhook
const express = require('express');
const crypto = require('crypto');
const bodyParser = require('body-parser');

const app = express();

app.use(bodyParser.json());

app.post('/webhook', (req, res) => {
    const secret = '<CLIENT_SECRECT>'; // Substitua pela sua chave <CLIENT_SECRECT>
    const signature = req.headers['x-deliverydireto-signature'];

    const bodyString = JSON.stringify(req.body);

    // Verificação de Segurança para garantir que a requisição recebida vem do Delivery Direto
    // A assinatura é composto pelo Hash HMAC SHA256 do corpo da requisição (body) onde a chave de criptografia é sua CLIENT_SECRET.
    const bodyHash = crypto.createHmac('sha256', secret)
                           .update(bodyString, 'utf-8')
                           .digest('hex');

    if (bodyHash !== signature) {
        // Retorne um HTTP status code error, sempre que houver algo errado
        res.status(401).send('Unauthorized');
        return;
    }

    // Lógica da sua aplicação... 
    console.log('Received Webhook:', req.body);

    // Complete a requisição com status code 200 para indicar sucesso
    res.status(200).send('OK');
});

const PORT = process.env.PORT || 3333;

app.listen(PORT, () => {
    console.log(`Webhook receiver listening on port ${PORT}`);
});

Para rodar o servidor basta utilizar o seguinte comando:

Rodando o servidor de exemplo
node index.js

Para testar o receptor, você pode publicar seu código em um servidor Web ou você pode testar localmente utilizando a ferramenta ngrok

Testando o receptor localmente utilizando o ngrok​

Assim que seu aplicativo estiver sendo executado com sucesso no localhost, você pode colocá-lo na Internet usando o ngrok:

  1. Se você ainda não é usuário do ngrok, basta se inscrever gratuitamente no ngrok.

  2. Baixe o agente ngrok.

  3. Vá para o painel do ngrok e copie seu Authtoken. (O agente ngrok usa o token de autenticação para fazer login na sua conta quando você inicia um túnel.)

  4. Inicie o ngrok executando o seguinte comando:

    ngrok http 3000

  5. O ngrok exibirá uma URL onde seu aplicativo localhost está exposto à Internet.

    Ngrok

  6. Copie a URL do ngrok e cadastre para receber os eventos do Webhook nesta URL:

    Exemplo do cadastro de um Endpoint para receber eventos via Webhook
    curl --location --request PUT 'https://deliverydireto.com.br/admin-api/v1/webhooks' \
    --header 'X-DeliveryDireto-ID: <X-DeliveryDireto-ID da loja>' \
    --header 'X-DeliveryDireto-Client-Id: <CLIENT_ID>' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <access_token>'
    --data '{
    "webhookUrl": "https://1a2b-3c4d-5e6f-7g8h-9i0j.sa.ngrok.io/webhook",
    "eventType": "ORDER_PLACED",
    "status": "ACTIVE"
    }'

No exemplo acima a propriedade webhookUrl no corpo da requisição contém o valor https://ede2-2804-214-88ea-a092-7c63-bcdb-b9ec-249.ngrok-free.app/webhook você deve substituir com os dados do endpoint.

Daí ao receber um novo pedido o Delivery Direto irá notificar com uma chamada POST HTTP na URL cadastrada.

Exemplo de evento recebido via Webhook

Tipos de eventos​

O campo eventType pode assumir os seguintes valores:

  • ORDER_PLACED: é disparado quando um pedido novo é criado.
  • ORDER_STATUS_CHANGED: é disparado quando um pedido tem o status alterado.
  • ORDER_EDITED: é disparado quando um pedido é editado.

Você pode cadastrar a mesma URL para os 3 tipos de eventos ou criar um endpoint diferente para cada tipo de evento.