Handshakes e challenges de webhooks

Webhooks permitem a interoperabilidade entre serviços e aplicações orientadas a eventos. Para garantir uma comunicação segura e confiável, alguns serviços implementam handshakes e challenges como parte do processo de registro da URL do webhook. Para entender os fundamentos, veja o que são webhooks e como eles funcionam.

Este guia explica o que são handshakes e challenges de webhooks, por que eles existem e como implementá-los.

Por que os serviços usam handshakes e challenges de webhooks?

Handshakes e challenges de webhooks são mecanismos de segurança usados para confirmar que a URL informada é válida e que existe um servidor pronto e disposto a receber eventos de webhook. Essa etapa de validação pode ser importante para evitar que URLs sejam registradas maliciosamente em servidores de terceiros na tentativa de criar um ataque de negação de serviço.

O que são handshakes de webhooks?

Um handshake de webhook é um processo de verificação que acontece quando você registra uma URL de webhook em um serviço pela primeira vez. O serviço envia uma requisição de verificação para a sua URL de webhook, e o seu servidor precisa responder com um token ou código pré-definido para confirmar o handshake.

Como funcionam os handshakes

1. Registro: você registra a URL do seu webhook no serviço.
2. Requisição de verificação: o serviço envia uma requisição de verificação para a URL do seu webhook.
3. Resposta: o seu servidor responde à requisição de verificação com uma resposta específica, normalmente um token pré-definido ou um código de status HTTP determinado.
4. Confirmação: se a resposta estiver correta, o serviço confirma a URL do webhook e passa a enviar eventos para ela.

Exemplo: implementando um handshake

Veja um exemplo de como implementar um handshake de webhook em Node.js usando Express:

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

// Middleware to parse JSON bodies
app.use(express.json());

// Endpoint to handle webhook handshake
app.post('/webhook', (req, res) => {
  const verificationToken = 'your-verification-token';
  
  // Check if the request contains the verification token
  if (req.body.token === verificationToken) {
    // Respond with the verification token to confirm the handshake
    res.status(200).send(verificationToken);
  } else {
    // Respond with a 400 status code if the token is invalid
    res.status(400).send('Invalid token');
  }
});

app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

O que são challenges de webhooks?

Um challenge de webhook é um mecanismo de segurança usado para garantir que as requisições de webhook recebidas são legítimas e não foram adulteradas. Os challenges normalmente envolvem o envio, pelo serviço, de um token ou código único a cada requisição de webhook, que o seu servidor precisa verificar.

Como funcionam os challenges

1. Entrega do evento: o serviço envia um evento para a URL do seu webhook, incluindo um token de challenge.
2. Verificação: o seu servidor verifica o token de challenge gerando um hash a partir do token com um segredo compartilhado, para garantir que a requisição vem de uma origem confiável.
3. Processamento: se o token for válido, o seu servidor processa o evento. Caso contrário, rejeita a requisição.

Exemplo: implementando um challenge

const express = require('express');
const crypto = require('crypto');
const app = express();
const port = 3000;

// Middleware to parse JSON bodies
app.use(express.json());

// Secret key used to verify the challenge token
const secret = 'your-secret-key';

// Endpoint to handle incoming webhook events
app.post('/webhook', (req, res) => {
  const challengeToken = req.headers['x-challenge-token'];
  
  // Verify the challenge token
  const hash = crypto.createHmac('sha256', secret)
                     .update(challengeToken)
                     .digest('hex');
  
  if (hash === req.body.expectedHash) {
    // Process the event if the token is valid
    console.log('Event received:', req.body.event);
    res.status(200).send('Event processed');
  } else {
    // Respond with a 400 status code if the token is invalid
    res.status(400).send('Invalid challenge token');
  }
});

app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

Conclusão

Handshakes e challenges de webhooks são mecanismos para verificar a legitimidade dos registros de webhook e proteger o seu servidor de callbacks indesejados vindos de serviços inesperados. Os exemplos deste guia mostram como implementar handshakes e challenges em Node.js com Express, mas os conceitos se aplicam a outras linguagens e frameworks. Para orientações mais completas sobre segurança, veja o nosso guia completo de segurança de webhooks.