> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
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](/pt/api-reference/guides/api-fundamentals/configure-webhooks)
## 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.
### 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](/pt/api-reference/webhooks/test-webhooks)
### 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.
Use o secret de assinatura do endpoint `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](/pt/api-reference/guides/api-fundamentals/configure-webhooks) para obter o secret do endpoint e o fluxo de trabalho de verificação.
#### Formato da assinatura:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
YCloud-Signature: t={timestamp},s={signature}
```
#### Algoritmo de verificação:
1. Extraia o timestamp (t) e a assinatura (s) do cabeçalho da solicitação (o timestamp é um timestamp Unix em segundos).
2. Construa o payload assinado: signed\_payload: `{timestamp}.{request_body}.`
3. Calcule a assinatura usando o algoritmo HMAC-SHA256:
```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
HMAC-SHA256(signed_payload, secret)
```
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 ser despriorizadas.
3. **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.77`
* `47.236.160.49`
Se o firewall corporativo, gateway ou servidor de webhook restringir o tráfego de entrada por IP de origem, adicione ambos os endereços à sua 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 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:
1. No painel da YCloud, acesse **Desenvolvedores** > **Webhooks**.
2. Abra o endpoint de webhook relevante e visualize seus logs de entrega.
3. 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.
4. 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.
Um registro com falha inclui o motivo de falha de entrega correspondente. Use a resposta e os detalhes 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 assinaturas do endpoint.
As entregas com falha são repetidas automaticamente de acordo com o [cronograma de novas tentativas](#retry-mechanism) abaixo. Revise 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 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](/pt/documentation/developer/create-and-configure-a-custom-app). 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.
Não dependa da repetição do webhook como uma estratégia de recuperação. Monitore seu endpoint, responda prontamente com um status `2xx` e investigue falhas nos logs de entrega de 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.
* **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
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.