EntrarTeste grátis

Integrações com webhooks

Atualizado em 20 de out. de 20265 min de leitura
Português
Nesta página

Webhooks empurram dados de evento em tempo real do Deskwoot pro seu próprio endpoint. Conversa criada, mensagem enviada, contato atualizado: escolhe os eventos que importam, passa uma URL, fazemos POST de JSON conforme eventos rolam. Cada entrega é HMAC-signed pra você verificar que realmente veio do Deskwoot. Útil pra sincronizar a CRM, disparar workflows custom ou logar eventos no seu data warehouse.

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

  1. Acesse Configurações > Webhooks no seu painel do Deskwoot.
  2. Clique em Adicionar webhook.
  3. Informe a URL do endpoint que deve receber os dados do evento. Ela precisa ser uma URL HTTPS publicamente acessível.
  4. Selecione os tipos de evento que você quer assinar (por exemplo, conversa criada, mensagem criada ou contato atualizado). Se nenhum for selecionado, todos os eventos são enviados.
  5. Clique em Criar webhook 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

Quais eventos posso subscrever?
Conversa criada, conversa atualizada, conversa atribuída, conversa resolvida, mensagem criada, contato criado, contato atualizado e CSAT enviado. Se nenhum evento for selecionado, o webhook recebe todos. Cada evento tem seu próprio payload em data; vê os API docs.
A entrega de webhook é assinada?
Sim. Cada request tem o header X-Deskwoot-Signature (sha256= seguido do HMAC-SHA256 em hex do body bruto, assinado com o secret do webhook) e o header X-Deskwoot-Event com o nome do evento. O painel não mostra o secret; um webhook criado pela REST API devolve o secret uma vez na resposta. Verifica a assinatura antes de processar pra se proteger de requests forjados.
Deskwoot retentará entregas falhas?
Uma vez. Se o primeiro POST falha, demora mais de 10 segundos ou seu endpoint retorna erro, o Deskwoot tenta de novo depois de 5 segundos. Se essa tentativa também falhar, o evento é descartado: monta seu endpoint pra ser idempotente e tolerante a quedas curtas.
Quão rápido webhooks são entregues?
O Deskwoot envia cada evento na hora em que ele acontece, sem fila. Seu endpoint tem 10 segundos pra responder; uma resposta mais lenta conta como entrega falha e ganha a única nova tentativa.
Preciso de HTTPS?
Sim. Só fazemos POST pra URLs HTTPS. HTTP é rejeitado no config. Não-negociável já que payloads contêm dados de cliente.
Qual o formato do request?
POST com Content-Type: application/json. O body é um objeto JSON com event, data (o payload do evento), timestamp e accountId. Vê os API docs pro data de cada evento.
Vou ganhar eventos duplicados?
Raramente, mas é possível durante a nova tentativa (network blips, seu endpoint retornando status ambíguo). O body não tem ID de evento, então usa o nome do evento junto com o ID do objeto em data (por exemplo o ID da mensagem) pra pular eventos já processados.
Posso filtrar eventos server-side antes de enviar?
Filtering no subscribe: sim, escolhe quais event types. Filtering content-based ('só conversas na inbox X'): não built-in; subscreve todos, filtra no seu endpoint.
O que acontece se meu endpoint cai por algumas horas?
Os eventos enviados durante a queda se perdem: o Deskwoot não guarda eventos além da única nova tentativa. Quando o endpoint voltar, recupera os dados pela REST API (Enterprise): lista as conversas ordenadas pela atividade mais recente e reconcilia o estado.
Posso mandar webhooks pra múltiplos endpoints?
Sim. Cria múltiplos webhooks cada um apontando pra URL diferente. Útil quando uma ferramenta precisa de todos os eventos e outra só de um subset.
Como testo antes de ir ao vivo?
Usa um serviço de URL temp tipo webhook.site ou RequestBin no setup. Inspeciona os payloads reais chegando, valida seu parser, depois troca pro seu endpoint de produção quando estiver confiante.

Este guia foi útil?

Continue lendo

Perguntar ao Fynn sobre este guia

Receba uma resposta curta deste guia e do resto da Central de Ajuda.

Ainda precisa de ajuda?

Fynn responde no chat a partir destes guias, e você também fala com a equipe por lá.

Enviar e-mail