# Webhooks e assinatura

Fonte: https://apiwpp.com/docs/guias/webhooks-e-assinatura
Seção: Guias
Atualizado em: 2026-09-29

Como receber os eventos, verificar a assinatura X-Sales-Signature, testar o endpoint, e como funcionam as novas tentativas e o reenvio de entregas.

A apiwpp envia cada evento com um `POST` ao `webhookBaseUrl` do projeto. A entrega é feita **pelo menos uma vez**: o mesmo evento pode chegar de novo, então aplique cada um de forma idempotente. Um projeto inativo não recebe webhooks.

## 1. Configure o endpoint

O endpoint e a assinatura são do projeto e mudam com [`PATCH /tenants/{id}`](https://apiwpp.com/docs/api/projetos/atualizar-projeto), com uma chave que tenha o escopo `webhooks:write`:

| Campo | O que é |
| --- | --- |
| `webhookBaseUrl` | A URL que recebe os eventos. Precisa ser **https**, sem credenciais na URL, e o host tem de resolver só para endereços públicos. Redirecionamentos não são seguidos |
| `webhookToken` | Um valor seu, enviado em toda entrega no cabeçalho `X-Webhook-Token` |
| `webhookSecret` | O segredo da assinatura HMAC. `null` ou `""` desliga a assinatura |
| `webhookHeaders` | Cabeçalhos extras enviados em toda entrega (`null` remove todos). Nunca substituem os de assinatura |
| `emitOutgoing` | `true` liga o evento `message.outgoing` |

`webhookToken`, `webhookSecret` e os valores de `webhookHeaders` nunca são devolvidos: a resposta traz só `hasWebhookSecret` e `webhookHeaderNames`. Guarde o segredo no cofre do servidor que recebe os eventos **antes** de enviá-lo; se ele se perder, defina outro.

**Definir o segredo e ligar message.outgoing**

```bash
WEBHOOK_SECRET=$(openssl rand -hex 32)

curl -s -X PATCH https://api.apiwpp.com/tenants/$TENANT_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhookSecret": "'$WEBHOOK_SECRET'", "emitOutgoing": true}'
```

Uma URL que não segue as regras é recusada com `400`.

## 2. Receba os eventos

Todo evento chega no mesmo envelope; `data` depende do `type`:

**message.delivery**

```json
{
  "type": "message.delivery",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "timestamp": "2026-09-25T12:00:02.000Z",
  "data": {
    "messageId": "3EB0C767D26A1D8A3F52",
    "status": "delivered",
    "recipient": "5511988887777",
    "clientRef": "pedido-1234",
    "jid": "5511988887777@s.whatsapp.net",
    "phone": "+5511988887777"
  }
}
```

| Campo | Descrição |
| --- | --- |
| `type` | O tipo do evento |
| `connectionId` | A conexão (o número) que gerou o evento |
| `tenantId` | O projeto |
| `externalId` | O seu identificador da conexão, ou `null` |
| `timestamp` | Quando o evento aconteceu (ISO 8601) |
| `data` | Os campos do evento |

**Ignore os tipos de evento que você não conhece** e os campos que não usa: o contrato só cresce (tipos e campos novos), nunca renomeia nem remove.

| `type` | Quando |
| --- | --- |
| [`connection.status`](https://apiwpp.com/docs/webhooks/connection-status) | A conexão abriu ou fechou, ou o WhatsApp mudou o que a conta pode fazer (`reason`) |
| [`message.incoming`](https://apiwpp.com/docs/webhooks/message-incoming) | Alguém escreveu para o número (texto, mídia, localização), numa conversa individual ou num grupo |
| [`message.outgoing`](https://apiwpp.com/docs/webhooks/message-outgoing) | O número enviou uma mensagem; só com `emitOutgoing: true` no projeto |
| [`message.delivery`](https://apiwpp.com/docs/webhooks/message-delivery) | Uma mensagem enviada mudou de status: `sent`, `delivered`, `read` ou `failed` |
| [`message.send_failed`](https://apiwpp.com/docs/webhooks/message-send-failed) | Um envio com `clientRef` não vai acontecer |
| [`message.reaction`](https://apiwpp.com/docs/webhooks/message-reaction) | Alguém reagiu a uma mensagem (ou removeu a reação) |
| [`contact.resolved`](https://apiwpp.com/docs/webhooks/contact-resolved) | Um remetente que chegou só com LID agora tem telefone |
| [`group.joined`](https://apiwpp.com/docs/webhooks/group-joined), [`group.left`](https://apiwpp.com/docs/webhooks/group-left), [`group.updated`](https://apiwpp.com/docs/webhooks/group-updated) | O número entrou num grupo, saiu dele, ou o grupo mudou |
| [`ping`](https://apiwpp.com/docs/webhooks/ping) | Só no teste do endpoint (passo 4) |

Os campos de cada evento estão na página dele, em [Webhooks](https://apiwpp.com/docs/webhooks).

> **Ordem e repetição**
>
> Uma entrega em nova tentativa pode chegar depois de eventos mais novos. Use o `timestamp` do envelope para ordenar e chaves como `messageId` + `status` para descartar repetições.

### Mídia recebida

Um [`message.incoming`](https://apiwpp.com/docs/webhooks/message-incoming) com mídia traz `data.media.url`, uma URL **assinada e temporária** do arquivo. Baixe-a sem credencial, exatamente como veio, até `data.media.expiresAt` (24 horas depois do recebimento, por padrão): veja [Baixar mídia](https://apiwpp.com/docs/api/midia/baixar-midia). Baixe o arquivo quando o evento chegar, em vez de guardar a URL, e trate a URL como um segredo: não a registre em log nem a repasse.

## 3. Verifique a assinatura

Com um `webhookSecret` definido, cada tentativa de entrega traz estes cabeçalhos:

| Cabeçalho | Conteúdo |
| --- | --- |
| `X-Sales-Timestamp` | Segundos unix do momento da tentativa (cada nova tentativa é assinada de novo) |
| `X-Sales-Signature` | `sha256=` + hex(HMAC-SHA256(`webhookSecret`, `timestamp` + `"."` + corpo bruto)) |
| `X-Webhook-Token` | O `webhookToken` do projeto, enviado sempre, com ou sem assinatura |
| `Content-Type` | `application/json` |

Para aceitar um evento:

1. Leia o **corpo bruto**, os bytes exatamente como chegaram. Nunca assine de novo um objeto já convertido de JSON: a serialização muda e a assinatura não confere.
2. Rejeite um `X-Sales-Timestamp` a mais de **300 segundos** do seu relógio: isso barra a repetição de entregas antigas.
3. Calcule o HMAC-SHA256 de `timestamp + "." + corpo` com o segredo e compare com `X-Sales-Signature` em **tempo constante**.
4. Responda `2xx` logo e processe o evento fora da requisição.

**Node.js**

```js
import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const SECRET = process.env.WHATSAPP_WEBHOOK_SECRET;
// Sem segredo não há o que verificar: o servidor não sobe
if (!SECRET) throw new Error('WHATSAPP_WEBHOOK_SECRET não está definido');
const TOLERANCE_SECONDS = 300;

function isSigned(rawBody, timestamp, signature) {
  if (!/^\d+$/.test(timestamp ?? '') || !signature) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;
  const mac = createHmac('sha256', SECRET).update(`${timestamp}.`).update(rawBody).digest('hex');
  const expected = Buffer.from(`sha256=${mac}`);
  const received = Buffer.from(signature);
  return expected.length === received.length && timingSafeEqual(expected, received);
}

const app = express();

// express.raw: o corpo chega como Buffer, sem ser convertido de JSON
app.post('/whatsapp/events', express.raw({ type: 'application/json' }), (req, res) => {
  if (!isSigned(req.body, req.get('X-Sales-Timestamp'), req.get('X-Sales-Signature'))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  queue.add(event); // processe fora da requisição
  res.sendStatus(204);
});
```

**PHP**

```php
<?php
$secret = getenv('WHATSAPP_WEBHOOK_SECRET');
if (!is_string($secret) || $secret === '') {
    // Sem segredo não há o que verificar: recuse tudo até configurá-lo
    http_response_code(500);
    exit;
}

$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_SALES_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_SALES_SIGNATURE'] ?? '';

$fresh = ctype_digit($timestamp) && abs(time() - (int) $timestamp) <= 300;
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

if (!$fresh || !hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true);
// Enfileire $event e processe depois
http_response_code(204);
```

**Python**

```python
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

SECRET = os.environ.get("WHATSAPP_WEBHOOK_SECRET", "")
# Sem segredo não há o que verificar: o servidor não sobe
if not SECRET:
    raise RuntimeError("WHATSAPP_WEBHOOK_SECRET não está definido")
TOLERANCE_SECONDS = 300

app = Flask(__name__)

def is_signed(raw_body: bytes, timestamp: str, signature: str) -> bool:
    if not timestamp.isdigit() or not signature:
        return False
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    mac = hmac.new(SECRET.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={mac}", signature)

@app.post("/whatsapp/events")
def whatsapp_events():
    raw_body = request.get_data()  # os bytes como chegaram
    if not is_signed(raw_body, request.headers.get("X-Sales-Timestamp", ""), request.headers.get("X-Sales-Signature", "")):
        abort(401)
    event = json.loads(raw_body)
    queue.put(event)  # processe fora da requisição
    return "", 204
```

Em Laravel, o corpo bruto é `$request->getContent()`, os cabeçalhos vêm de `$request->header(...)` e o segredo vem de `config(...)`, nunca de `getenv()`: com `php artisan config:cache`, o arquivo `.env` deixa de ser lido e `getenv()` devolve `false`.

> **Nunca verifique com um segredo vazio**
>
> Um HMAC com chave vazia pode ser calculado por qualquer pessoa. Se o segredo não chegou ao processo (variável ausente ou vazia, cache de configuração), o verificador tem de recusar tudo, como nos exemplos acima, em vez de comparar assinaturas.

Sem `webhookSecret`, as entregas não são assinadas: confira pelo menos o `X-Webhook-Token`, também em tempo constante.

## 4. Teste o endpoint

[`POST /tenants/webhook-test`](https://apiwpp.com/docs/api/projetos/testar-webhook) envia um evento [`ping`](https://apiwpp.com/docs/webhooks/ping) à URL informada, com os mesmos cabeçalhos, a mesma assinatura, o mesmo limite de 10 segundos e as mesmas regras de URL das entregas reais. Nada é salvo, e o ping não entra no registro de entregas.

- Com `tenantId`, o ping é assinado com o segredo guardado do projeto (a menos que você mande `webhookSecret`). O token e os cabeçalhos guardados só são usados quando `webhookBaseUrl` é a URL salva do projeto.
- Para outra URL, mande `webhookToken` junto: sem ele, a resposta é `400`.

**Testar o endpoint salvo**

```bash
curl -s -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/hooks/whatsapp", "tenantId": "'$TENANT_ID'"}'
```

Resposta `200`

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

`status` é o que o seu endpoint respondeu (`null` sem resposta), e `error` diz o que falhou, como `"timeout"` quando os 10 segundos acabaram. No `ping`, `connectionId`, `tenantId` e `externalId` vêm `null`, e `data.message` é `"ping from WhatsApp Gateway admin"`.

## 5. Respostas e novas tentativas

- Responda **`2xx` em até 10 segundos**; o corpo da resposta é ignorado. Faça o trabalho pesado depois, fora da requisição.
- Qualquer outra resposta (`3xx`, `4xx`, `5xx`), um erro de rede ou o tempo esgotado conta como falha. Um redirecionamento é registrado como falha, sem ser seguido.
- Uma entrega falha é tentada de novo depois de cerca de 2, 4, 8, 16 e 32 segundos: **6 tentativas** no total. Depois disso, ela fica no estado `dead`.
- Depois de 5 falhas seguidas, a apiwpp pausa as entregas do projeto por 30 segundos, e a pausa dobra a cada teste que falha, até 5 minutos. Uma única entrega testa o endpoint antes de retomar; os eventos esperam na fila.
- Um evento que passa 24 horas sem ser entregue fica `dead`.

## 6. Registro e reenvio

[`GET /webhooks/deliveries`](https://apiwpp.com/docs/api/registros/listar-entregas-de-webhook) (escopo `logs:read`) lista cada evento enviado, dos mais novos para os mais antigos, com o estado (`delivered`, `retry` ou `dead`), o status HTTP recebido, o erro, a latência, as tentativas, se foi assinado e o corpo enviado. Filtre com `state` e `tenantId`; `limit` vai até 200 (padrão 60). A resposta também traz `counts` por estado e `stats` com a taxa de sucesso e a latência média.

**Entregas mortas**

```bash
curl -s "https://api.apiwpp.com/webhooks/deliveries?state=dead&limit=50" \
  -H "Authorization: Bearer $API_KEY"
```

Quando o seu endpoint voltar (escopo `webhooks:write`):

- [`POST /webhooks/deliveries/{id}/resend`](https://apiwpp.com/docs/api/registros/reenviar-entrega) reenvia uma entrega `dead` ou `retry`, na hora e com novas tentativas. Uma entrega já feita responde `409`, e uma cujo corpo não foi registrado também (corpos acima de 256 KB não são guardados).
- [`POST /webhooks/deliveries/resend-dead`](https://apiwpp.com/docs/api/registros/reenviar-entregas-mortas) reenvia todas as entregas `dead` dos seus projetos, até 1000 por chamada, das mais novas para as mais antigas, e responde `{ "requeued": 3 }`. Com mais de 1000, chame de novo. As que não têm o corpo guardado continuam `dead` e voltam a ocupar as 1000 vagas da próxima chamada, que começa sempre pelas mais novas: se `requeued` vier abaixo de 1000 e ainda houver entregas `dead` mais antigas, reenvie essas uma a uma com `POST /webhooks/deliveries/{id}/resend`.

Por padrão, o registro guarda as entregas por 7 dias. Para não perder eventos numa indisponibilidade longa, confira o estado `dead` depois de cada incidente e reenvie.

## Próximos passos

- [Webhooks](https://apiwpp.com/docs/webhooks): o envelope e os campos de cada evento.
- [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens): os envios que geram `message.delivery` e `message.send_failed`.
- [LID e contact.resolved](https://apiwpp.com/docs/guias/lid-e-contact-resolved): remetentes que chegam sem telefone.
- [Uso e registros](https://apiwpp.com/docs/guias/uso-e-registros): os registros de mensagens e de entregas.
