Pular para o conteúdo

Testar webhook

POST/tenants/webhook-test

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.

Ver em Markdown

Corpo da requisição

webhookBaseUrlstringobrigatório

Endereç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.

webhookTokenstring

Vai 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 | null

Cabeçalhos personalizados do ping, por nome; null: nenhum. Ausente: os cabeçalhos guardados do projeto de tenantId, só quando webhookBaseUrl é o endereço salvo.

chaves livres, valores string
webhookSecretstring | null

Segredo 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 · uuid

Projeto 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

Respostas: código de status, erro e descrição
CódigoErro e descrição
200O 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.
400O 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.
400Falta webhookToken, e webhookBaseUrl não é o endereço salvo no projeto de tenantId (ou tenantId não veio).
400FST_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.
401Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. A chave de um projeto desativado também responde 401.
403A chave não tem o escopo webhooks:write; a mensagem de erro cita o escopo que falta.
404tenantId não é um projeto seu (Tenant not found): o de outra pessoa responde igual a um que não existe. Nada é enviado.
429Requisiçõ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

Esta página ajudou? · Atualizado em 28 set 2026