Você pode encontrar orientações de integração mais especializadas na documentação para desenvolvedores: Documentação para Desenvolvedores - Guia de Integração de Webhook
O que é um Webhook
Um webhook é um mecanismo de retorno de chamada 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 assim a necessidade de sondagem frequente de interface.Criar um Webhook
1. Adicionar 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 os 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. Verificar a assinatura do webhook
Sempre verifique a assinatura para garantir que a solicitação tenha sido originada na YCloud e não tenha sido adulterada.
secret de assinatura do endpoint para verificar o cabeçalho YCloud-Signature. Armazene o segredo com segurança no seu servidor. Consulte o Guia de Integração de Webhook para obter o segredo do endpoint e o fluxo de trabalho de verificação.
Formato da assinatura:
Algoritmo de verificação:
- Extraia o carimbo de data/hora (t) e a assinatura (s) do cabeçalho da solicitação (o carimbo de data/hora é um carimbo de data/hora Unix em segundos).
-
Construa o payload assinado como
{timestamp}.{request_body}usando exatamente o corpo bruto da solicitação. Não adicione um ponto final após o corpo. -
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 ter a prioridade reduzida.
- Processamento assíncrono (recomendado)
- Retorne 200 OK imediatamente .
- 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.7747.236.160.49
A inclusão de IPs na lista de permissões é um controle de rede adicional. Continue a verificar o cabeçalho
YCloud-Signature para cada solicitação de webhook.Verificar registros de entrega de webhook
A YCloud grava 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 registros de entrega antes de escalonar o problema:- No painel da YCloud, acesse Desenvolvedores > Webhooks.
-
Abra o endpoint de webhook relevante e visualize seus registros de entrega.
- Use um ou mais filtros para encontrar a tentativa de entrega:
- Status: Mostra entregas com sucesso ou com falha.
- Evento: Filtra pelo tipo de evento de webhook.
- ID do Evento: Pesquisa por um ID de evento específico da YCloud.
- ID dos Dados: Para eventos de mensagem, insira o ID da mensagem para localizar 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 todas as WABAs da 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 corresponde às assinaturas de evento configuradas, a YCloud o envia para cada URL de webhook aplicável. Se você precisar rotear diferentes WABAs para diferentes URLs de webhook, 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 evento para esse aplicativo.O que acontece se todas as sete tentativas de envio do webhook falharem?
Se o seu serviço não tiver se recuperado após a sétima tentativa, a YCloud interromperá automaticamente as tentativas para esse evento. O seu sistema não receberá o evento automaticamente após a interrupção das novas tentativas. 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.Tratamento de erros
Mecanismo de repetição:
Se o seu serviço retornar um código de status diferente de 2xx ou falhar ao responder, a YCloud tentará novamente de forma automática:- Cronograma de tentativas: 10 segundos → 30 segundos → 5 minutos → 30 minutos → 1 hora → 2 horas → 2 horas.
- Número máximo de tentativas: 7 vezes.
- Após 7 falhas: O evento não será mais repetido.
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