Webhooks

Atualizado em

Onde: Definições > Integrações > Webhooks

Para que serve:

"Encaminhe os eventos recebidos para o seu servidor." O SyBox envia uma cópia de cada evento do WhatsApp escolhido para um endereço no seu servidor, assim que ele acontece. Os webhooks cobrem apenas números do WhatsApp. Messenger, Instagram, Telegram, e-mail e SMS não são enviados.

Quem pode abrir: o administrador principal e membros da equipe com a permissão "Gerenciar números do WhatsApp". Para criar um webhook ou reativar um que estava pausado, você também precisa da permissão "Mostrar o número do contato", pois as cópias incluem os números de telefone reais dos clientes.

Eventos que você pode escolher:

  • "Mensagem recebida": um cliente enviou uma mensagem.
  • "Estado da mensagem": uma mensagem enviada por você foi enviada, entregue, lida ou falhou.
  • "Reação": um cliente reagiu a uma mensagem.
  • "Transcrição de voz" (uma opção extra): uma mensagem de voz é retida por um curto período, até cerca de dois minutos, para que seu texto transcrito possa ser enviado com ela. Fica desativada a menos que você a ative.

Como adicionar um webhook

  1. Vá para Definições > Integrações > Webhooks.
    Settings, Webhooks: an active webhook with its last result, and the "Add webhook" button
  2. Clique em "Adicionar webhook".
    The new webhook window: its name and the address it calls
  3. Digite um "Nome".
  4. Digite a "URL do destino". Deve ser "Um endereço https público que possamos alcançar". Endereços http simples e endereços de rede privada ou interna são recusados.
  5. Em "Eventos", ative pelo menos um evento. "Mensagem recebida" fica ativada por padrão.
  6. Opcional: ative a "Transcrição de voz" para receber mensagens de voz junto com o texto.
  7. Em "Números", deixe "Todos os números" ativado para cobrir todos os números do WhatsApp. Ou desative e marque apenas os números que desejar.
  8. Clique em Salvar.
  9. Uma janela mostra a "Chave de assinatura". "Copie agora — só é mostrada uma vez." Salve-a no seu servidor.

Sobre os envios:

  • Cada envio usa o mesmo formato dos próprios webhooks do WhatsApp da Meta.
  • Cada envio é assinado com sua chave de assinatura da mesma forma que a Meta assina seus webhooks. Se o seu servidor já valida os webhooks da Meta, ele pode validar os do SyBox usando sua chave do SyBox.
  • Se o seu servidor não responder com sucesso, o SyBox tenta novamente várias vezes, aguardando mais tempo a cada tentativa, por cerca de uma hora. Depois disso, ele desiste daquele evento.
  • O mesmo evento pode às vezes chegar duas vezes, por exemplo, após um tempo limite esgotado. Seu servidor deve lidar com mensagens duplicadas.

Como testar um webhook

  • O SyBox não tem um botão de "enviar teste" para webhooks. Para testar um:
  • Certifique-se de que o webhook esteja ativo e cubra o número que você usará.
  • Envie uma mensagem de WhatsApp para esse número a partir de outro telefone.
    To test a webhook: "HTTP 200" marked on the screen in SyBox
  • Volte para Definições > Integrações > Webhooks. O cartão mostra a última resposta do seu servidor, com o horário. Uma resposta de sucesso (por exemplo, "HTTP 200") aparece em verde. Um erro aparece em vermelho. "Último envio: nunca" significa que nada foi enviado ainda.

Como editar, pausar ou excluir um webhook

  1. Clique em Editar para alterar o nome, endereço, eventos ou números.
    To edit, pause or delete a webhook: "Edit" marked on the screen in SyBox
  2. Para substituir a chave de assinatura, digite uma nova em "Chave de assinatura". Deixe em branco para manter a chave atual ("Deixe em branco para manter a chave atual").
  3. Clique em Ativar / Desativar para pausá-lo. Eventos que chegarem enquanto estiver pausado ficam em espera. Se você o reativar em breve, eles serão enviados.
  4. Clique em Excluir e confirme: "Eliminar este webhook?".

Regras e mensagens:

  • Nome e URL do destino são obrigatórios, e pelo menos um evento deve estar ativado. Caso contrário, você verá "Dados incompletos".
  • Um endereço que não seja https público é recusado com "Um endereço https público que possamos alcançar".
Perdi a chave de assinatura.

Ela não pode ser mostrada novamente. Edite o webhook, digite uma nova chave criada por você em "Chave de assinatura", salve e use essa nova chave no seu servidor.

Meu webhook nunca recebe nada.

Verifique estas quatro coisas: (1) O webhook está ativado. (2) Pelo menos um evento está selecionado. (3) Ele cobre o número de WhatsApp correto, ou "Todos os números". (4) Seu espaço de trabalho possui algum número de WhatsApp conectado, já que os webhooks transmitem apenas eventos do WhatsApp. Em seguida, veja o resultado do último envio no cartão.

O cartão mostra um erro em vermelho, como HTTP 404 ou 500.

O SyBox alcançou seu endereço, mas seu servidor respondeu com um erro. Verifique o endereço e os logs do seu servidor.

Não consigo criar um webhook. Diz que não tenho permissão.

Criar um webhook, ou reativar um, requer tanto "Gerenciar números do WhatsApp" quanto "Mostrar o número do contato". Fale com o seu administrador.