Quando você cria um webhook, especifica uma URL e se inscreve em tipos de eventos. Quando ocorre um evento ao qual seu webhook está inscrito, o Fluid enviará uma solicitação HTTP com dados sobre o evento para a URL que você especificou. Se o seu servidor estiver configurado para escutar entregas de webhook nessa URL, ele poderá executar uma ação quando receber uma.

Este artigo descreve como escrever código para permitir que seu servidor escute e responda a entregas de webhook. Você testará seu código usando seu computador como servidor local.

Para lidar com entregas de webhook, você precisa escrever código que irá:

• Inicializar seu servidor para escutar solicitações para a URL do seu webhook

• Ler os cabeçalhos HTTP e o corpo da solicitação

• Executar a ação desejada em resposta à solicitação
  

Você pode usar qualquer linguagem de programação que possa executar no seu servidor.

Os exemplos a seguir imprimem uma mensagem quando uma entrega de webhook é recebida. No entanto, você pode modificar o código para executar outra ação, como fazer uma solicitação à API do Fluid ou enviar uma mensagem no Slack.

Este exemplo usa Node.js e a biblioteca Express para definir rotas e lidar com solicitações HTTP. Para mais informações, consulte expressjs.com

Este exemplo requer que seu computador execute o Node.js versão 12 ou superior e npm versão 6.12.0 ou superior. Para mais informações, consulte nodejs.org

Para usar este exemplo, você deve instalar o node.js e a biblioteca express no seu projeto Node.js. Por exemplo:

npm install nodejs

instalar express

npm install express

const express = require('express');
const bodyParser = require('body-parser');
const crypto = require('crypto');

const app = express();
const port = 3000;

// Middleware to parse JSON bodies as text,
// so we dont get issues like "prop":1.0 being changed to "prop":1
// as the payload is used for signature-256 validation
app.use(bodyParser.text({
   type: 'application/json'
}))

// Function to validate the X-Hub-Signature header
function validateSignature(req, res, next) {
  
    const sharedSecret = '#######'; // Replace with your shared secret
    const signature = req.headers['x-hub-signature-256'];
    const payload = req.body;
  
    if (!signature) {
    console.log(`X-Hub-Signature header missing`); 
        return res.status(400).send('X-Hub-Signature-256 header missing');
    }

  const hmac = crypto.createHmac('sha256', sharedSecret);
  const calculatedSignature = hmac.update(payload).digest('hex');

     if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from('sha256=' + calculatedSignature))) {
      console.log(`X-Hub-Signature-256 is VALID`);
        next();
    } else {
    console.log(`X-Hub-Signature-256 is INVALID`);
        return res.status(403).send('Invalid X-Hub-Signature-256');
    }
}

  app.post('/', validateSignature, (req, res) => {

  const jsonData = JSON.parse(req.body);
  const prettifiedJson = JSON.stringify(jsonData, null, 2);

  console.log('Received VALID POST request with body:', prettifiedJson);

  res.json(prettifiedJson); // Echo back the request body
});

// Start the server
app.listen(port, () => {
    console.log(`Server is listening at http://localhost:${port}`);
});

Para testar seu webhook, você pode usar seu computador como servidor local. Se tiver problemas com essas etapas, consulte Solução de problemas de webhooks.

node FILE_NAME

Substitua FILE_NAME pelo nome do seu arquivo, por exemplo server.js. Você deverá ver uma saída informando que o servidor está sendo executado na porta 3000.

Para testar seu webhook localmente, você pode usar uma URL de proxy de webhook para encaminhar webhooks do Fluid para o seu computador. Este artigo usa o ngrok https://ngrok.com para fornecer uma URL de proxy de webhook e encaminhar webhooks.

1. Siga as instruções em https://ngrok.com/download para instalar a versão correta do ngrok para o seu sistema operacional. O cadastro no ngrok é gratuito.

   Depois de se cadastrar, faça login no painel e anote o token de autenticação https://dashboard.ngrok.com/get-started/your-authtoken, você precisará dele como parte da instalação.

   Você também pode seguir o próprio guia de introdução a webhooks deles aqui https://ngrok.com/docs/integrations/hostedhooks/webhooks para informações adicionais.

   Os detalhes abaixo são para instalação no Windows.
   

2. Abra um shell de comando do Windows e execute o seguinte comando.

   choco install ngrok

3. Autentique o ngrok; seu token pode ser encontrado aqui https://dashboard.ngrok.com/get-started/your-authtoken após o cadastro no ngrok.

   ngrok config add-authtoken <### Token ###>

4. Para receber webhooks encaminhados do ngrok, execute o seguinte comando no seu terminal. Substitua PORT pela porta onde seu servidor local está escutando.

   ngrok http PORT

5. Para receber webhooks encaminhados do ngrok, execute o seguinte comando no seu terminal. Substitua PORT pela porta onde seu servidor local está escutando.

   ngrok http PORT

   

6. Anote o valor da URL do ngrok (destacado na captura de tela acima); esta é a URL pública que você usará para configurar Webhooks para os quadros do Fluid. Os eventos enviados para esta URL serão encaminhados para o seu servidor local escutando na porta 3000.  Neste exemplo, a URL é "https://a346-185-245-255-247.ngrok-free.app"
   

   Nota: Cada vez que você executar ngrok http PORT, você receberá uma nova URL pública; será necessário atualizar as configurações de webhook do Fluid adequadamente. Consulte Como configurar a integração de Webhooks com os Quadros do Fluid

Crie um webhook com as seguintes configurações. Para mais informações, consulte Como configurar a integração de Webhooks com os Quadros do Fluid.

• Para a URL, use a URL exibida no painel do ngrok http://localhost:4040 obtida anteriormente, por exemplo 
  

1. Acione seu webhook. Por exemplo, se você configurou seu webhook de ação para se inscrever no evento de criação, crie uma nova ação. 

2. Navegue até o painel do ngrok em http://localhost:4040. Na aba de inspeção, você deverá ver um evento que corresponde ao evento que você acionou. Isso indica que o Fluid enviou com sucesso uma entrega de webhook para a URL que você especificou na configuração. Você também pode inspecionar os detalhes do cabeçalho Http enviados pelo Fluid e/ou reproduzir a mensagem novamente.

   

3. Na janela do terminal onde você executou node FILE_NAME, você deverá ver a mensagem de evento correspondente ao evento que foi enviado.

4. Em ambas as janelas do terminal, pressione Ctrl+C para parar seu servidor local e interromper a escuta de webhooks encaminhados.

Agora que você testou seu código localmente, pode fazer alterações para usar seu webhook em produção. Para mais informações, consulte "Próximas etapas." Se tiver tido problemas ao testar seu código, tente as etapas em Solução de problemas de webhooks.

Se você não vir os resultados esperados descritos nas etapas de teste, tente o seguinte:

• Certifique-se de que seu webhook está usando a URL do proxy de webhook (URL do ngrok encontrada no painel  http://localhost:4040). Para mais informações sobre as configurações do seu webhook, consulte Como configurar a integração de Webhooks com o Fluid Boards.

• Certifique-se de que seu webhook usa o tipo de conteúdo JSON.

• Certifique-se de que tanto o cliente ngrok quanto o servidor local estejam em execução. Você terá esses processos rodando em duas janelas de terminal separadas.

• Certifique-se de que seu servidor está escutando na mesma porta onde o ngrok está encaminhando os webhooks. Todos os exemplos neste artigo usam a porta 3000.

• Verifique se há mensagens de erro nas janelas do terminal onde você está executando o cliente ngrok e o servidor local.

• Verifique a URL do proxy de webhook no ngrok. Você deverá ver um evento que corresponde ao evento que você acionou. Isso indica que o Fluid enviou com sucesso uma entrega de webhook para a URL de payload que você especificou.
  
  

Este artigo demonstrou como escrever código para lidar com entregas de webhook. Também demonstrou como testar seu código usando seu computador ou codespace como servidor local e encaminhando entregas de webhook do Fluid para o seu servidor local via ngrok.com. Depois de concluir os testes do seu código, você pode querer modificá-lo e implantá-lo em um servidor.

Este artigo forneceu exemplos básicos que exibem uma mensagem quando uma entrega de webhook é recebida. Você pode querer modificar o código para executar alguma outra ação. Por exemplo, você poderia modificar o código para:

• Enviar uma mensagem no Slack

• Registrar eventos

• Atualizar uma ferramenta externa

No seu código que lida com entregas de webhook, você deve validar que a entrega é do Fluid  antes de processar a entrega. Para mais informações, consulte Validando Webhooks.

Este artigo demonstrou como usar seu computador ou codespace como servidor enquanto você desenvolve seu código. Quando o código estiver pronto para uso em produção, você deve implantá-lo em um servidor dedicado.

Ao fazer isso, pode ser necessário atualizar seu código para refletir o host e a porta onde seu servidor está escutando.

Depois de ter um servidor configurado para receber tráfego de webhook do Fluid, atualize a URL nas configurações do webhook do seu fluid board. Pode ser necessário atualizar a rota que seu código manipula para corresponder à parte do caminho da nova URL. 

Você não deve usar ngrok.com para encaminhar seus webhooks em produção.

Você deve buscar seguir as melhores práticas com seus webhooks. Para mais informações, consulte Melhores práticas de webhook.

Solução de problemas de webhooks
Melhores práticas de webhook
Eventos e payloads de webhook