# connection.status

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

A conexão abriu, fechou ou foi restringida.

`POST` para o `webhookBaseUrl` do projeto.

O socket da conexão abriu ou fechou, ou o WhatsApp mudou o que a conta pode fazer. Uma abertura traz `status: open` e o número pareado em `phoneNumber`, sem `reason`. Um fechamento traz o motivo em `reason` e, em `willReconnect`, se a apiwpp reconecta sozinha: com `true` ela continua tentando, com espera crescente, e o próximo `status: open` diz que deu certo; com `false` ela parou e espera alguém, com um QR code novo ou uma reconexão explícita.

Como toda entrega de webhook é feita pelo menos uma vez, aplique-o de forma idempotente: use o `timestamp` do envelope para ignorar um status mais antigo que o último que você guardou.

**Os motivos de um fechamento.** Todos vêm com `status: close`, `willReconnect` e `statusCode`:

`transient` (`willReconnect: true`): queda de rede ou erro do lado do WhatsApp, como um `503`. A apiwpp tenta de novo, com espera crescente, até abrir.

`restart_required` (`willReconnect: true`): o WhatsApp pediu um socket novo, o que é normal logo depois do pareamento. A reconexão é imediata.

`replaced` (`willReconnect: false`): outro cliente assumiu a sessão (em geral, `statusCode` `440`). A conexão espera uma reconexão explícita com [`POST /tenants/{id}/connections/{connId}/connect`](https://apiwpp.com/docs/api/projetos/reconectar-conexao). Raramente, um `replaced` é seguido de um `open` sem que ninguém tenha reconectado: numa falha da infraestrutura, outra instância pode abrir a sessão por alguns instantes, e a conexão é retomada sozinha quando ela sai.

`qr_not_scanned` (`willReconnect: false`): ninguém escaneou os QR codes de uma conexão que nunca foi pareada. Conecte de novo para uma nova tentativa.

`logged_out` (`willReconnect: false`): a sessão acabou do lado do WhatsApp; o aparelho foi desconectado no celular, removido ou bloqueado (em geral, `statusCode` `401`). É preciso parear de novo, com um QR code novo.

`manual` (`willReconnect: false`): alguém chamou [`POST /connections/{id}/disconnect`](https://apiwpp.com/docs/api/conexoes/desconectar) ou [`POST /tenants/{id}/connections/{connId}/disconnect`](https://apiwpp.com/docs/api/projetos/desconectar-conexao-do-projeto). A conexão fica parada até ser conectada de novo.

`passkey_required`: o QR code foi escaneado, mas o pareamento não terminou porque o WhatsApp pediu uma passkey (chave de acesso) ao celular. `status` é `close`, sem `phoneNumber` (a conexão nunca confirmou um número), sem `willReconnect` e sem `statusCode`, e nenhum QR code novo é gerado até a conexão ser conectada de novo. Veja [Quando o WhatsApp pede uma passkey](https://apiwpp.com/docs/guias/parear-um-numero#quando-o-whatsapp-pede-uma-passkey).

`reachout_timelock`: o WhatsApp colocou a conta num bloqueio temporário de novas conversas, depois de um erro `463` num envio ou de uma notificação dele. Não é um fechamento: `status` é o status atual da conexão, normalmente `open`, e `reachoutTimelock` diz até quando o bloqueio vale. Até `reachoutTimelock.endsAt`, ou até um evento com `reachout_timelock_lifted`, todo envio da fila é descartado sem ser tentado, e os que têm `clientRef` geram [`message.send_failed`](https://apiwpp.com/docs/webhooks/message-send-failed) com `reason: reachout_timelocked`. O evento chega de novo se o WhatsApp prolongar o bloqueio ou mudar o tipo dele. Veja [Bloqueio temporário de novas conversas](https://apiwpp.com/docs/guias/limites-de-envio#bloqueio-temporario-de-novas-conversas).

`reachout_timelock_lifted`: o WhatsApp informou que um bloqueio em vigor acabou antes do prazo, e `reachoutTimelock` vem com `active: false`. Um bloqueio que termina no `endsAt` anunciado não gera este evento: conte com o horário. Um bloqueio sem fim anunciado (`endsAt: null`) vale até o WhatsApp suspendê-lo, e a apiwpp volta a consultar o WhatsApp no máximo uma vez por minuto antes de recusar um envio.

**Quando avisar alguém.** `willReconnect` é a decisão da apiwpp, não uma promessa. Avise na hora num fechamento com `willReconnect: false`, e num com `true` só se nenhum `open` chegar dentro do seu próprio prazo. Decida pelo `reason`, nunca pelo `statusCode`, que serve só para diagnóstico. Para consultar o status a qualquer momento, use [`GET /connections/{id}/qr`](https://apiwpp.com/docs/api/conexoes/qr-code-e-status).

**Projeto inativo.** Desativar o projeto fecha as conexões dele sem nenhum `connection.status`: um projeto inativo não recebe webhooks.

**Entrega.** Um `POST` com `Content-Type: application/json` ao `webhookBaseUrl` do projeto, feito **pelo menos uma vez**; um projeto inativo não recebe webhooks. Responda `2xx` em até 10 segundos: o corpo da resposta é ignorado, e um redirecionamento (`3xx`) não é seguido e conta como falha. Uma entrega que falha é tentada de novo depois de cerca de 2, 4, 8, 16 e 32 segundos, **6 tentativas** no total, e então fica `dead`. Depois de 5 falhas seguidas, as entregas do projeto ficam em pausa de 30 segundos a 5 minutos, e um evento que passa 24 horas sem ser entregue também fica `dead`. Uma nova tentativa pode chegar depois de eventos mais novos: ordene pelo `timestamp` do envelope. Reenvie as entregas `dead` com [`POST /webhooks/deliveries/{id}/resend`](https://apiwpp.com/docs/api/registros/reenviar-entrega) ou [`POST /webhooks/deliveries/resend-dead`](https://apiwpp.com/docs/api/registros/reenviar-entregas-mortas).

**Assinatura.** `X-Webhook-Token` vem sempre, com o `webhookToken` do projeto, junto com os `webhookHeaders` personalizados. Com um `webhookSecret`, cada tentativa também traz `X-Sales-Timestamp` (segundos unix da tentativa) e `X-Sales-Signature`: calcule `"sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + corpo))` sobre os bytes do corpo exatamente como chegaram, compare em tempo constante e rejeite um `X-Sales-Timestamp` a mais de 300 segundos do seu relógio. Veja [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura).

## 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 | O tipo do evento, que decide o formato de `data`. Ignore os tipos que você não conhece: a lista de eventos pode crescer. (sempre "connection.status") |
| `connectionId` | `string · uuid` | sim | O id (UUID) da conexão, ou seja, do número, que gerou o evento. |
| `tenantId` | `string · uuid` | sim | O id (UUID) do projeto dono da conexão. |
| `externalId` | `string \| null` | sim | O `externalId` que você informou ao criar a conexão, para ligá-la a um registro seu. `null` quando a conexão foi criada sem ele. |
| `timestamp` | `string · date-time` | sim | Quando o evento foi gerado, em ISO 8601 (UTC). É o mesmo em todas as tentativas de entrega; o momento de cada tentativa vem no cabeçalho `X-Sales-Timestamp`. |

## Campos de `data`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `status` | `string` | sim | O status da conexão: `open` (aberta) ou `close` (fechada). Num evento com `reachout_timelock` ou `reachout_timelock_lifted`, é o status do momento, que também pode ser `connecting` (conectando). Valores: `"connecting"`, `"open"`, `"close"`. |
| `phoneNumber` | `string` | não | Os dígitos do número pareado, quando conhecido (por exemplo, `5511900000001`). Não vem com `passkey_required`. |
| `reason` | `string` | não | Por que o evento foi enviado. Num fechamento: `transient`, `restart_required`, `replaced`, `qr_not_scanned`, `logged_out`, `manual` ou `passkey_required`. Com o status atual: `reachout_timelock` ou `reachout_timelock_lifted`. Não vem numa abertura. Valores: `"transient"`, `"restart_required"`, `"replaced"`, `"qr_not_scanned"`, `"logged_out"`, `"manual"`, `"reachout_timelock"`, `"reachout_timelock_lifted"`, `"passkey_required"`. |
| `willReconnect` | `boolean` | não | Só num fechamento com `transient`, `restart_required`, `replaced`, `qr_not_scanned`, `logged_out` ou `manual`: se a apiwpp reconecta sozinha. É `true` só com `transient` e `restart_required`. |
| `statusCode` | `number \| null` | não | Só junto com `willReconnect`. O código de desconexão do WhatsApp (por exemplo, `401` sessão encerrada, `440` sessão substituída, `503` erro do WhatsApp, `515` reinício pedido), ou `null` quando não houve um. Serve para diagnóstico: decida pelo `reason`. |
| `reachoutTimelock` | `object` | não | O bloqueio temporário de novas conversas. Vem com `reachout_timelock` e `reachout_timelock_lifted`. |
| `reachoutTimelock.active` | `boolean` | sim | Se o bloqueio está em vigor: `true` com `reachout_timelock`, `false` com `reachout_timelock_lifted`. |
| `reachoutTimelock.endsAt` | `string · date-time \| null` | sim | Quando o bloqueio termina (ISO 8601), ou `null` quando o WhatsApp não informou um fim ou quando o bloqueio acabou. |
| `reachoutTimelock.enforcementType` | `string \| null` | sim | O tipo de restrição informado pelo WhatsApp, por exemplo `DEFAULT` ou `BIZ_QUALITY`; `null` quando não há bloqueio. |

## Exemplo

```json
{
  "type": "connection.status",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "timestamp": "2026-09-24T12:00:00.000Z",
  "data": {
    "status": "open",
    "phoneNumber": "5511900000001"
  }
}
```

Guia: [Parear um número](https://apiwpp.com/docs/guias/parear-um-numero).
