Testar webhook
Envia um evento ping assinado ao endereço informado, com os mesmos cabeçalhos, a mesma assinatura, o mesmo limite de 10 segundos e as mesmas regras de URL das entregas reais: redirecionamentos não são seguidos, e um host que resolve para um endereço não público é recusado na conexão. Nada é salvo; a resposta conta o que o endpoint respondeu. Escopo necessário: webhooks:write.
Corpo da requisição
webhookBaseUrlstringobrigatórioEndereço que recebe o ping, com as mesmas regras do webhookBaseUrl de um projeto: https, sem usuário e senha na URL, e o host precisa resolver só para endereços públicos.
webhookTokenstringVai no cabeçalho X-Webhook-Token. Obrigatório, a menos que tenantId venha e webhookBaseUrl seja o endereço salvo no projeto: aí vale o token guardado.
webhookHeadersobject | nullCabeçalhos personalizados do ping, por nome; null: nenhum. Ausente: os cabeçalhos guardados do projeto de tenantId, só quando webhookBaseUrl é o endereço salvo.
webhookSecretstring | nullSegredo que assina o ping (X-Sales-Timestamp e X-Sales-Signature); null ou "": sem assinatura. Ausente: o segredo guardado do projeto de tenantId, se houver.
tenantIdstring · uuidProjeto cujas credenciais guardadas completam o teste: o segredo dele assina o ping quando webhookSecret não vem, e o token e os cabeçalhos dele valem para o endereço salvo. Precisa ser um projeto seu.
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | O que o endpoint respondeu: ok, status (o status HTTP; null quando nenhuma resposta voltou), latencyMs e error (null quando deu certo; timeout quando o limite de 10 segundos estourou; senão, o motivo da falha, como HTTP 500). Nada é salvo. |
| 400 | O webhookBaseUrl foi recusado: precisa ser https, sem usuário e senha na URL, e o host precisa resolver só para endereços públicos. error diz qual regra falhou. |
| 400 | Falta webhookToken, e webhookBaseUrl não é o endereço salvo no projeto de tenantId (ou tenantId não veio). |
| 400 | FST_ERR_VALIDATIONO corpo não segue o schema da operação (por exemplo, sem webhookBaseUrl, ou tenantId que não é um UUID); message diz o que está errado. |
| 401 | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. A chave de um projeto desativado também responde 401. |
| 403 | A chave não tem o escopo webhooks:write; a mensagem de erro cita o escopo que falta. |
| 404 | tenantId não é um projeto seu (Tenant not found): o de outra pessoa responde igual a um que não existe. Nada é enviado. |
| 429 | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After. Veja Limites.Cabeçalho: Retry-After |
Detalhes
Com tenantId, o projeto precisa ser seu; senão, a resposta é 404 (Tenant not found). O segredo guardado do projeto assina o ping quando webhookSecret não vem. O token e os cabeçalhos guardados só são reaproveitados quando webhookBaseUrl é exatamente o endereço salvo no projeto: para testar outro endereço, envie webhookToken.
O ping chega com connectionId, tenantId e externalId nulos e data.message igual a ping from WhatsApp Gateway admin. ok é true quando o endpoint respondeu 2xx dentro de 10 segundos; uma resposta 3xx conta como falha, porque o redirecionamento não é seguido.
Guia: Webhooks e assinatura