---
title: "Webhooks: receber eventos da conta — Documentação | WordPane Cloud"
url: "https://wordpane.cloud/documentacao/webhooks/"
description: "Configure destinos, valide assinaturas e acompanhe as entregas. Consulte os passos e orientações para usar o painel WordPane Cloud."
language: "pt-BR"
generatedAt: "2026-10-31T14:05:07.042Z"
contentType: "public-page"
pricingSource: "https://app.wordpane.cloud/api/public/plan-catalog"
---

[Central de documentação](https://wordpane.cloud/documentacao/)

API e integrações

# Webhooks: receber eventos da conta

Configure destinos, valide assinaturas e acompanhe as entregas.

**Documentação técnica da área do cliente**

Os exemplos usam dados fictícios e não executam chamadas nesta página. Nunca informe sua credencial real aqui.

## Cadastre o destino

O titular com e-mail confirmado acessa Conta → API e integrações → Webhooks → Adicionar webhook. Informe nome, URL e eventos; defina o limite para saldo baixo quando aplicável. Há até 10 destinos ativos por conta. A URL deve usar HTTPS na porta 443 com IPv4 público, sem credenciais, parâmetros de consulta ou fragmentos. Guarde o segredo mostrado uma única vez, configure-o no receptor e use Enviar teste.

## Escolha os eventos

Os eventos usam POST e application/json, com identificadores e dados mínimos. Não enviam mensagens completas dos chamados nem credenciais. Respostas antigas e instalações já concluídas não são reenviadas ao cadastrar um destino.

### Permissões e detalhes

**`server.installation.completed`**: server_key

**`ticket.reply.created`**: ticket_id, reply_id, from_support

**`balance.low`**: balance, threshold e currency, ao cruzar para baixo do limite; não há aviso retroativo se o saldo já estava baixo.

### JSON

```
{
"id": "00000000-0000-4000-8000-000000000001",
"type": "ticket.reply.created",
"created_at": "2026-10-17T12:00:00Z",
"account_id": 123,
"data": {
"ticket_id": 456,
"reply_id": 789,
"from_support": true
}
}
```

## Valide a assinatura

WordPane-Signature usa t=TIMESTAMP,v1=ASSINATURA. Calcule HMAC-SHA256 sobre timestamp + "." + corpo bruto, compare em tempo constante e rejeite diferenças superiores a 5 minutos. WordPane-Event-Id deve coincidir com id no corpo. O exemplo usa módulos nativos do Node.js.

### Node.js

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

export function verifyWordPane(rawBody, headers, secret, now = Date.now()) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(
headers['wordpane-signature'] ?? ''
);
if (!Buffer.isBuffer(rawBody) || !match || !secret) return null;
if (Math.abs(now / 1000 - Number(match[1])) > 300) return null;
const expected = createHmac('sha256', secret)
.update(match[1] + '.').update(rawBody).digest();
const received = Buffer.from(match[2], 'hex');
if (!timingSafeEqual(expected, received)) return null;
try {
const event = JSON.parse(rawBody.toString('utf8'));
return event && typeof event.id === 'string'
&& event.id === headers['wordpane-event-id'] ? event : null;
} catch { return null; }
}
```

**Antes de continuar**

Preserve o Buffer original antes de qualquer parser JSON. Reconstruir o corpo com JSON.stringify pode invalidar a assinatura. Guarde o segredo no servidor e sincronize o relógio. O exemplo valida a assinatura; não implementa servidor HTTP, persistência ou processamento do evento.

## Confirme sem processar duas vezes

Responda com HTTP 2xx após validar e registrar o evento de forma durável. Use id para deduplicar. Há até 6 tentativas automáticas com espera crescente; o ID é mantido e cada tentativa recebe uma assinatura com timestamp novo. Redirecionamentos não são seguidos. O timeout de conexão é 5 segundos e o total é 10 segundos.

**Antes de continuar**

Para trabalho em segundo plano, registre o evento em uma fila durável antes de confirmar. Instalações e saldo são verificados a cada minuto; respostas entram na fila ao serem criadas.

## Edite, renove o segredo ou reenvie

Editar altera nome, URL, eventos e limite de saldo, mantendo o segredo. Trocar a URL cancela entregas anteriores pendentes ou com falha. Remover um evento cancela suas entregas pendentes ou com falha. Renovar segredo invalida o anterior imediatamente: configure o novo no receptor. Não é possível editar ou renovar durante uma entrega em andamento.

**Antes de continuar**

Reenviar aparece para falhas finais de um webhook ativo e agenda uma tentativa adicional, mantendo ID, corpo e contagem acumulada. Um evento repetido não deve gerar outro processamento no receptor.

## Avisos e retenção de históricos

O acompanhamento verifica falhas recorrentes a cada 5 minutos e avisa o titular pelo sino, sem e-mail ou WhatsApp. O mesmo incidente não repete avisos enquanto estiver aberto; novas ocorrências respeitam intervalo mínimo de 24 horas. O acompanhamento interno depende do agendador e não substitui monitoramento externo de disponibilidade.

**Antes de continuar**

Chamadas da API e entregas concluídas ou canceladas são mantidas por 90 dias; falhas finais, por 180 dias desde a última atualização. A limpeza diária ocorre às 03:15 de Brasília. Entregas pendentes e chaves de deduplicação são preservadas.

Atualizado em 17 de outubro de 2026.

[Consultar outros guias](https://wordpane.cloud/documentacao/)

---
Fonte oficial: https://wordpane.cloud/documentacao/webhooks/
Esta é uma representação da página pública. A data de geração não indica alteração editorial.