# ping

Fonte: https://apiwpp.com/docs/webhooks/ping
Seção: Webhooks
Atualizado em: 2026-09-28

O teste de um endpoint de webhook.

`POST` para o `webhookBaseUrl` do projeto.

O evento que [`POST /tenants/webhook-test`](https://apiwpp.com/docs/api/projetos/testar-webhook) 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.

## Cabeçalhos da entrega

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `X-Webhook-Token` | `string` | sim | O `webhookToken` do projeto, em toda entrega. Pode ser definido, mas nunca é devolvido pela API: troque-o com [`PATCH /tenants/{id}`](https://apiwpp.com/docs/api/projetos/atualizar-projeto). Os `webhookHeaders` personalizados do projeto também são enviados. |
| `X-Sales-Timestamp` | `string` | não | 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-Signature` | `string` | não | 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

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `type` | `string` | sim | Sempre `ping`. (sempre "ping") |
| `connectionId` | `null` | sim | Sempre `null`: o teste não vem de uma conexão. |
| `tenantId` | `null` | sim | Sempre `null`. |
| `externalId` | `null` | sim | Sempre `null`. |
| `timestamp` | `string · date-time` | sim | Quando o teste foi enviado. |

## Campos de `data`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `message` | `string` | sim | Texto fixo: `ping from WhatsApp Gateway admin`. (sempre "ping from WhatsApp Gateway admin") |

## Exemplo

```json
{
  "type": "ping",
  "connectionId": null,
  "tenantId": null,
  "externalId": null,
  "timestamp": "2026-09-25T12:00:00.000Z",
  "data": {
    "message": "ping from WhatsApp Gateway admin"
  }
}
```

Guia: [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura).
