Você pode encontrar orientações de integração mais especializadas na documentação do desenvolvedor: Documentação do desenvolvedor - Guia de integração de Webhook
O que é um Webhook
Um webhook é um mecanismo de callback HTTP orientado a eventos. Quando um evento específico ocorre no sistema da 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 sondagem frequente da interface.Criar um Webhook
1. Adicione um endpoint de Webhook.
Faça login no painel da YCloud, navegue até Desenvolvedor > Webhooks e clique em Adicionar endpoints para criar um endpoint de webhook.
Enter your HTTPS endpoint URL, add an optional description, and choose the events before confirming.
2. Insira o endereço do endpoint para monitorar eventos relevantes.
A YCloud oferece várias opções de eventos para WhatsApp, SMS, Contato, E-mail e muito mais.Você pode encontrar todos os payloads relevantes para os eventos aqui: Payload do Webhook
Use Search event to find the subscriptions your endpoint needs.
3. Verifique a assinatura do webhook
Sempre verifique a assinatura para garantir que a solicitação tenha origem na YCloud e não tenha sido adulterada.
secret para verificar o cabeçalho YCloud-Signature. Armazene o secret com segurança no seu servidor. Consulte o Guia de integração de Webhook para obter o secret do endpoint e o fluxo de trabalho de verificação.
Formato da assinatura:
Algoritmo de verificação:
- Extraia o timestamp (t) e a assinatura (s) do cabeçalho da solicitação (o timestamp é um timestamp Unix em segundos).
-
Construa o payload assinado: signed_payload:
{timestamp}.{request_body}. -
Calcule a assinatura usando o algoritmo HMAC-SHA256:
- Compare a assinatura calculada com a assinatura recebida.
4. Responder ao Webhook
- Retorne um código de status 2xx (por exemplo, 200, 201, 204)
- Qualquer resposta diferente de 2xx acionará uma nova tentativa.
- Resposta rápida (recomendado em até 6 segundos)
- Respostas rápidas aumentam a prioridade do seu webhook.
- Respostas lentas (>10 segundos) podem ser despriorizadas.
- Processamento assíncrono (recomendado)
- Retorne 200 OK imediatamente .
- Processe os eventos em tarefas/filas em segundo plano.
Permitir 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.7747.236.160.49
A inclusão de IPs na lista de permissões é um controle de rede adicional. Continue verificando o cabeçalho
YCloud-Signature para 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 encaminhar o problema:- No painel da YCloud, acesse Desenvolvedores > Webhooks.
-
Abra o endpoint de webhook relevante e visualize seus logs de entrega.
- Use um ou mais filtros para encontrar a tentativa de entrega:
- Status: mostre entregas bem-sucedidas ou com falha.
- Evento: filtre pelo tipo de evento de webhook.
- ID do evento: pesquise por um ID de evento específico da YCloud.
- ID dos dados: para eventos de mensagem, insira o ID da mensagem para encontrar seu registro de entrega.
- Selecione um registro para revisar o horário de entrega, o payload da solicitação, o corpo da resposta e o código de status HTTP.
Perguntas frequentes
Se eu configurar várias URLs de webhook, os eventos de cada WABA na conta serão enviados para todas elas?
Sim. Os endpoints de webhook configurados em Desenvolvedores > Webhooks são globais para a conta da YCloud. Quando um evento de qualquer WABA na conta corresponder às assinaturas de eventos configuradas, a YCloud o enviará para cada URL de webhook aplicável. Se precisar rotear diferentes WABAs para URLs de webhook distintas, 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 nova tentativa do webhook falharem?
Se o seu serviço não tiver se recuperado após a sétima tentativa, a YCloud interromperá automaticamente as novas tentativas para esse evento. O seu sistema não receberá o evento automaticamente depois que as novas tentativas forem interrompidas. Após restabelecer seu serviço, entre em contato com o Suporte da YCloud para solicitar uma 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 estar mais qualificados para repetição.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.
- Contagem máxima de tentativas: 7 vezes.
- Após 7 falhas: O evento não será mais tentado novamente.
Suspensão de URL:
Para proteger os recursos do sistema, URLs com falhas frequentes serão suspensas temporariamente:- Condições de disparo: 200 falhas por minuto ou tempo cumulativo de falhas 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