ping
O teste de um endpoint de webhook.
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-TokenstringsempreO 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-TimestampstringSó 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.
X-Sales-SignaturestringSó 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.
Envelope
typestringsempre presenteSempre ping.
connectionIdnullsempre presenteSempre null: o teste não vem de uma conexão.
tenantIdnullsempre presenteSempre null.
externalIdnullsempre presenteSempre null.
timestampstring · date-timesempre presenteQuando o teste foi enviado.
Campos de data
messagestringsempre presenteTexto fixo: ping from WhatsApp Gateway admin.