Implementar um webhook eficiente é mais fácil do que parece. Com algumas boas práticas, você cria um código que gerencia o webhook de forma rápida e confiável. Isso melhora o processamento do payload e garante entregas mais ágeis, sem enfileiramento ou perda de performance. Como resultado, uma integração simples que beneficia tanto você quanto seus usuários.

Problemas que webhooks mal criados podem causar

Pense em um webhook como um entregador de pacotes. Se ele demora para confirmar que entregou o pacote, a central pode mandar outro entregador, causando atrasos e confusão. Da mesma forma, se seu webhook não responde rápido, a Zenvia pode reenviar o payload, gerando filas e sobrecarga no seu sistema. Um webhook bem feito evita esses problemas.

Implementação

Zenvia SDK (recomendado)

Para aproveitar ao máximo a API da Zenvia, siga boas práticas ao criar webhooks. Isso melhora sua experiência, reduz filas e ajuda outros clientes e a Zenvia. Nossa recomendação é usar o SDK da Zenvia: ele já vem estruturado para alta performance. Se preferir, temos instruções para criar seu próprio webhook com a mesma eficiência.

Exemplo com o SDK

import { Client, TextContent, WebhookController } from '@zenvia/sdk';
const client = new Client('SUA_ZENVIA_API_TOKEN');
const webhook = new WebhookController({
  client,
  port: 3000,
  messageEventHandler: (messageEvent) => {
    const { from, to, channel } = messageEvent.message;
    const reply = new TextContent('Oi, seja bem vindo!');
    client.getChannel(channel).sendMessage(to, from, reply);
  },
});
webhook.init();

Nesse exemplo, retornamos uma mensagem. O forte da biblioteca (@zenvia/sdk) é que respondemos à requisição assim que recebemos o payload e retornamos OK.

Com o SDK, você recebe o payload, processa a mensagem e responde automaticamente, tudo de forma otimizada.

Webhook do zero

Se preferir criar seu próprio webhook, é importante retornar o status 200 imediatamente para confirmar o recebimento do payload.

Exemplo com Express

import express from 'express';
const app = express();
app.use(express.json());
app.post('/webhook', async (req, res) => {
  res.sendStatus(200);  // Retorna 200 imediatamente pra Zenvia  
  processWebhook(req.body);
});
async function processWebhook(payload) {
  // TODO: Adicionar a sua  lógica de processamento de webhooks aqui.
}
app.listen(3000, () => {
  console.log('Server running on port 3000');
});
export default app;

Retornar o 200 rápido evita reenvios desnecessários, mantendo seu servidor leve. Para segurança, valide o payload, verificando apenas as propriedades esperadas. O SDK já faz isso automaticamente, reduzindo o risco de requisições maliciosas. Se criar do zero, não pule essa etapa.

Criar um webhook eficiente é simples e poderoso. Com o SDK da Zenvia, você tem uma solução pronta. Se optar por criar do zero, essas práticas garantem rapidez e segurança. Escolha o que funciona para você e aproveite uma integração sem complicações!