Pular para o conteúdo

ping

POSTpara o webhookBaseUrl do projeto

O teste de um endpoint de webhook.

Ver em Markdown

O evento que POST /tenants/webhook-test envia para testar um endpoint antes de salvá-lo, e o único meio de recebê-lo. Ele chega com os mesmos cabeçalhos, a mesma assinatura e o mesmo limite de 10 segundos das entregas reais, mas não vem de uma conexão nem de um projeto: connectionId, tenantId e externalId são sempre null. Nada é salvo.

Há uma única tentativa, sem as novas tentativas das entregas reais, e o ping não entra no registro de entregas. O resultado volta na resposta do próprio teste: ok, status (o código HTTP que o seu endpoint respondeu, null sem resposta), latencyMs e error ("timeout" quando os 10 segundos acabam).

Só uma resposta 2xx conta como sucesso. Redirecionamentos não são seguidos: um 3xx é falha ("redirect not followed: HTTP 301 to …"), porque o destino do redirecionamento receberia o X-Webhook-Token.

Cabeçalhos: Content-Type: application/json e X-Webhook-Token sempre, mais os webhookHeaders do teste (ou os guardados, quando a URL é a salva do projeto). Com segredo, também X-Sales-Timestamp e X-Sales-Signature, calculados como numa entrega real. O segredo é o webhookSecret do teste ou, sem ele, o guardado do projeto informado em tenantId; webhookSecret: "" manda o ping sem assinatura.

O token é o webhookToken do teste. Sem ele, o gateway só usa o token guardado quando webhookBaseUrl é a URL salva do projeto; fora disso, o teste responde 400 sem enviar nada.

ping não faz parte do enum type da especificação (WebhookEventEnvelope), e o seu envelope tem null onde os outros eventos têm identificadores. Trate-o antes de validar o envelope, ou ignore os tipos que você não conhece e responda 2xx, como a especificação pede.

Guia: Webhooks e assinatura

Cabeçalhos da entrega

X-Webhook-Tokenstringsempre

O webhookToken do projeto, em toda entrega. Pode ser definido, mas nunca é devolvido pela API: troque-o com PATCH /tenants/{id}. Os webhookHeaders personalizados do projeto também são enviados.

X-Sales-Timestampstring

Só quando o projeto tem um webhookSecret: segundos unix desta tentativa de entrega (as novas tentativas são assinadas de novo). Rejeite um que esteja a mais de 300 s do seu relógio.

formato `^\d+$`
X-Sales-Signaturestring

Só quando o projeto tem um webhookSecret: "sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + rawBody)). Calcule sobre os bytes do corpo exatamente como recebidos, nunca sobre um objeto serializado de novo, e compare em tempo constante.

formato `^sha256=[0-9a-f]{64}$`

Envelope

typestringsempre presente

Sempre ping.

sempre "ping"
connectionIdnullsempre presente

Sempre null: o teste não vem de uma conexão.

tenantIdnullsempre presente

Sempre null.

externalIdnullsempre presente

Sempre null.

timestampstring · date-timesempre presente

Quando o teste foi enviado.

Campos de data

messagestringsempre presente

Texto fixo: ping from WhatsApp Gateway admin.

sempre "ping from WhatsApp Gateway admin"
Esta página ajudou? · Atualizado em 28 set 2026