Integrações com webhooks

Os webhooks no Deskwoot são chamadas HTTP que disparam quando algo acontece na sua caixa de entrada (nova conversa, nova mensagem, mudança de status), permitindo sincronizar eventos de suporte com um CRM, acionar uma automação externa ou registrá-los no seu próprio banco de dados, tudo sem precisar consultar a API repetidamente. Seja para atualizar um CRM, acionar uma notificação em uma ferramenta externa ou registrar eventos de suporte no seu próprio banco de dados, os webhooks oferecem uma forma leve e orientada a eventos de manter tudo sincronizado.

Este guia mostra como criar um webhook, escolher os eventos certos e resolver problemas comuns.

Criando um webhook

Acesse Configurações > Webhooks no seu painel do Deskwoot.
Clique em Adicionar webhook.
Informe a URL do endpoint que deve receber os dados do evento. Ela precisa ser uma URL HTTPS publicamente acessível.
Selecione os tipos de evento que você quer assinar (por exemplo, conversa criada, mensagem enviada ou contato atualizado).
Clique em Salvar para ativar o webhook.

Depois de salvo, o Deskwoot enviará uma requisição HTTP POST com um payload JSON para a URL especificada toda vez que um evento correspondente ocorrer.

Dicas de boas práticas

Use apenas endpoints HTTPS. Isso garante que os dados do evento sejam criptografados em trânsito e protege as informações sensíveis dos clientes.
Assine de forma seletiva. Escolha apenas os tipos de evento que você realmente precisa. Assinar todos os eventos pode gerar um grande volume de requisições e dificultar a depuração.
Responda rápido. Seu endpoint deve retornar um código de status 2xx o mais rápido possível. Transfira qualquer processamento pesado para uma tarefa em segundo plano para evitar timeouts.
Registre os payloads recebidos. Durante a configuração inicial, registre o JSON bruto para inspecionar a estrutura do payload e montar a sua integração com precisão.
Mantenha seu endpoint idempotente. Em casos raros, um webhook pode ser entregue mais de uma vez. Projete o seu handler de modo que processar o mesmo evento duas vezes não cause ações duplicadas.

Solução de problemas

Não está recebendo eventos? Verifique se a URL do seu endpoint está correta, publicamente acessível e retorna uma resposta 2xx. Firewalls ou regras de lista de IPs permitidos podem bloquear as requisições recebidas em silêncio.
Formato de payload inesperado? Confirme que você está fazendo o parse do corpo da requisição como JSON (Content-Type: application/json). Confira os logs do seu servidor em busca de erros de parse.
Eventos chegando atrasados? Pequenos atrasos podem ocorrer em períodos de alto tráfego. Se os atrasos persistirem, confirme que o seu servidor não está limitando nem enfileirando as conexões recebidas.

Perguntas frequentes

Posso configurar vários webhooks para endpoints diferentes?

Sim. Você pode criar quantos webhooks precisar, cada um apontando para uma URL diferente e assinando tipos de evento diferentes. Isso é útil quando serviços distintos precisam reagir a eventos diferentes.

O que acontece se o meu endpoint ficar temporariamente fora do ar?

Se o Deskwoot receber uma resposta diferente de 2xx ou a requisição expirar, a entrega é considerada com falha. Monitore o tempo de atividade do seu endpoint para minimizar eventos perdidos e considere implementar um mecanismo de registro de reserva do seu lado.

Existe uma forma de testar um webhook antes de colocá-lo no ar?

Uma abordagem comum é usar uma ferramenta de inspeção de requisições (como uma URL pública temporária que registra as requisições recebidas) como seu endpoint durante a configuração. Isso permite revisar a estrutura do payload e confirmar a entrega antes de apontar o webhook para o seu sistema de produção.