# Testar webhook

Fonte: https://apiwpp.com/docs/api/projetos/testar-webhook
Seção: Projetos
Atualizado em: 2026-09-28

`POST /tenants/webhook-test`

Envia um evento [`ping`](https://apiwpp.com/docs/webhooks/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`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |
| `Content-Type` | sim | `application/json` |

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `webhookBaseUrl` | `string` | sim | 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. |
| `webhookToken` | `string` | não | 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. |
| `webhookHeaders` | `object \| null` | não | 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) |
| `webhookSecret` | `string \| null` | não | 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. |
| `tenantId` | `string · uuid` | não | 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. |

## Exemplo de requisição

### cURL

```bash
curl -X POST \
  https://api.apiwpp.com/tenants/webhook-test \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookBaseUrl": "https://crm.example.com/api/whatsapp/events",
    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61"
  }'
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/tenants/webhook-test`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    webhookBaseUrl: 'https://crm.example.com/api/whatsapp/events',
    tenantId: '3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61',
  }),
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->post("https://api.apiwpp.com/tenants/webhook-test", [
        'webhookBaseUrl' => 'https://crm.example.com/api/whatsapp/events',
        'tenantId' => '3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61',
    ]);
```

### Python

```python
import requests

response = requests.post(
    "https://api.apiwpp.com/tenants/webhook-test",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "webhookBaseUrl": "https://crm.example.com/api/whatsapp/events",
        "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
    },
)
```

## Respostas

| Código | Erro | 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_VALIDATION` | O 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](https://apiwpp.com/docs/referencia/limites). Cabeçalhos: `Retry-After`. |

### 200 OK

```json
{
  "ok": true,
  "status": 200,
  "latencyMs": 184,
  "error": null
}
```

## 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](https://apiwpp.com/docs/guias/webhooks-e-assinatura).
