Saltar para o conteúdo principal
Você pode encontrar orientações de integração mais especializadas na documentação para desenvolvedores: Documentação para Desenvolvedores - Webhook Integration Guide

O que é um Webhook

Um webhook é um mecanismo de callback HTTP orientado a eventos. Quando um evento específico ocorre dentro do sistema YCloud, ele envia proativamente os dados do evento por meio de uma solicitação HTTPS para uma URL pré-configurada (o endereço do webhook), eliminando a necessidade de consultas frequentes (polling) à interface.

Criar um Webhook

1. Adicionar um endpoint de Webhook.

Faça login no painel da YCloud, navegue até Developer > Webhooks e clique em Add Endpoints para criar um endpoint de webhook.
Caixa de diálogo Add Endpoints vazia com Endpoint URL em destaque.

Enter your HTTPS endpoint URL, add an optional description, and choose the events before confirming.

2. Inserir o endereço do endpoint para monitorar eventos relevantes.

A YCloud oferece várias opções de eventos para WhatsApp, SMS, Contact, Email e muito mais.
Você pode encontrar todos os payloads relevantes para os eventos aqui: Webhook Payload
Menu Webhook Events com nomes de eventos e Search event.

Use Search event to find the subscriptions your endpoint needs.

3. Verificar a assinatura do webhook

Sempre verifique a assinatura para garantir que a solicitação seja originada da YCloud e não tenha sido adulterada.
Use o segredo de assinatura do endpoint secret para verificar o cabeçalho YCloud-Signature. Armazene o segredo com segurança em seu servidor. Consulte o Webhook Integration Guide para obter o segredo do endpoint e o fluxo de trabalho de verificação.

Formato da assinatura:

Algoritmo de verificação:

  1. Extraia o timestamp (t) e a assinatura (s) do cabeçalho da solicitação (o timestamp é um carimbo de data/hora Unix em segundos).
  2. Construa o payload assinado como {timestamp}.{request_body} usando o corpo bruto exato da solicitação. Não adicione um ponto final após o corpo.
  3. Calcule a assinatura usando o algoritmo HMAC-SHA256:
  4. Compare a assinatura calculada com a assinatura recebida.

4. Responder ao Webhook

  1. Retorne um código de status 2xx (por exemplo, 200, 201, 204)
    • Qualquer resposta diferente de 2xx acionará uma nova tentativa.
  2. Resposta rápida (recomendado em até 6 segundos)
    • Respostas rápidas aumentam a prioridade do seu webhook.
    • Respostas lentas (>10 segundos) podem ter a prioridade reduzida.
  3. Processamento assíncrono (recomendado)
    • Retorne imediatamente 200 OK.
    • Processe eventos em tarefas/filas em segundo plano.

Permitir os IPs de entrega de webhook da YCloud

A YCloud envia solicitações de webhook a partir dos seguintes endereços IP de servidor:
  • 8.219.65.77
  • 47.236.160.49
Se o firewall, gateway ou servidor de webhook da sua empresa restringir o tráfego de entrada por IP de origem, adicione ambos os endereços à lista de permissões. Permitir apenas um endereço pode fazer com que algumas entregas de webhook sejam bloqueadas.
A inclusão de IPs na lista de permissões é um controle de rede adicional. Continue a verificar o cabeçalho YCloud-Signature em cada solicitação de webhook.

Verificar logs de entrega de webhook

A YCloud registra as tentativas de entrega de webhook para que você possa confirmar se um evento foi enviado e solucionar falhas de entrega. Se o seu sistema não receber um webhook esperado, verifique os logs de entrega antes de escalar o problema:
  1. No painel da YCloud, acesse Developers > Webhooks.
  2. Abra o endpoint de webhook relevante e visualize seus logs de entrega. Imagem
  3. Use um ou mais filtros para encontrar a tentativa de entrega:
  • Status: Mostra entregas com sucesso ou com falha.
  • Event: Filtra pelo tipo de evento de webhook.
  • Event ID: Pesquisa por um ID de evento específico da YCloud.
  • Data ID: Para eventos de mensagens, insira o ID da mensagem para localizar seu registro de entrega.
  1. Selecione um registro para conferir o horário de entrega, o payload da solicitação, o corpo da resposta e o código de status HTTP.
Um registro com falha inclui o motivo correspondente da falha na entrega. Use os detalhes da resposta e do erro para verificar a URL do endpoint, a disponibilidade, o tempo de processamento e a resposta HTTP.
Quando um webhook esperado estiver ausente, pesquise primeiro pelo ID da mensagem ou ID do evento. Isso ajuda a distinguir uma falha de entrega de um evento que não corresponde às inscrições do endpoint.
As entregas com falha são repetidas automaticamente de acordo com o cronograma de repetição abaixo. Consulte a tentativa mais recente nos logs durante a solução de problemas.

Perguntas frequentes

Se eu configurar várias URLs de webhook, os eventos de todas as WABAs da conta serão enviados para todas elas?

Sim. Os endpoints de webhook configurados em Developers > Webhooks são globais para a conta da YCloud. Quando um evento de qualquer WABA na conta corresponde às assinaturas de eventos configuradas, a YCloud o envia para cada URL de webhook aplicável. Se precisar encaminhar WABAs diferentes para URLs de webhook diferentes, use aplicativos personalizados. Um aplicativo personalizado permite atribuir números de telefone específicos do WhatsApp e configurar um endpoint de webhook dedicado e assinaturas de eventos para esse aplicativo.

O que acontece se todas as sete tentativas de reenvio do webhook falharem?

Se o seu serviço não tiver se recuperado após a sétima tentativa, a YCloud interrompe automaticamente as novas tentativas para esse evento. O seu sistema não receberá o evento automaticamente depois que as tentativas forem interrompidas. Após restaurar seu serviço, entre em contato com o Suporte da YCloud para solicitar a repetição do webhook. A disponibilidade de repetição é limitada: a YCloud só pode reenviar eventos que ainda estejam disponíveis no sistema, e eventos históricos mais antigos podem não ser mais elegíveis para repetição.
Não dependa da repetição de webhook como estratégia de recuperação. Monitore seu endpoint, responda prontamente com um status 2xx e investigue falhas nos logs de entrega do webhook o mais rápido possível.

Tratamento de erros

Mecanismo de nova tentativa:

Se o seu serviço retornar um código de status diferente de 2xx ou não responder, a YCloud tentará novamente de forma automática:
  • Cronograma de novas tentativas: 10 segundos → 30 segundos → 5 minutos → 30 minutos → 1 hora → 2 horas → 2 horas.
  • Número máximo de novas tentativas: 7 vezes.
  • Após 7 falhas: nenhuma nova tentativa será feita para o evento.

Suspensão de URL:

Para proteger os recursos do sistema, URLs com falhas frequentes serão suspensas temporariamente:
  • Condições de acionamento: 200 falhas por minuto ou tempo acumulado de falha superior a 10 minutos por minuto
  • Duração da suspensão: 3 minutos
  • Durante a suspensão: nenhuma solicitação de webhook será enviada
  • Após a suspensão: restauração automática