---
title: "Webhooks: recibir eventos de la cuenta — Documentación | WordPane Cloud"
url: "https://wordpane.cloud/es/documentacao/webhooks/"
description: "Configure destinos, valide firmas y consulte las entregas."
language: "es"
generatedAt: "2026-10-31T14:05:07.042Z"
contentType: "public-page"
pricingSource: "https://app.wordpane.cloud/api/public/plan-catalog"
---

[Centro de documentación](https://wordpane.cloud/es/documentacao/)

API e integraciones

# Webhooks: recibir eventos de la cuenta

Configure destinos, valide firmas y consulte las entregas.

**Documentación técnica del área de clientes**

Los ejemplos usan datos ficticios y no ejecutan solicitudes en esta página. Nunca introduzca su credencial real aquí.

## Registre el destino

El titular con correo confirmado accede a Cuenta → API e integraciones → Webhooks → Añadir webhook. Indique nombre, URL y eventos; defina el límite de saldo bajo cuando corresponda. Hay hasta 10 destinos activos por cuenta. La URL debe usar HTTPS en el puerto 443 con IPv4 pública, sin credenciales, parámetros ni fragmentos. Guarde el secreto que se muestra una vez, configúrelo en el receptor y use Enviar prueba.

## Elija los eventos

Los eventos usan POST y application/json con identificadores y datos mínimos. No envían mensajes completos de tickets ni credenciales. Las respuestas antiguas e instalaciones ya terminadas no se reenvían al registrar un destino.

### Permisos y detalles

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

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

**`balance.low`**: balance, threshold y currency al cruzar por debajo del límite; no hay aviso retroactivo si el saldo ya era bajo.

### 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 la firma

WordPane-Signature usa t=TIMESTAMP,v1=FIRMA. Calcule HMAC-SHA256 sobre timestamp + "." + cuerpo original, compare en tiempo constante y rechace diferencias superiores a 5 minutos. WordPane-Event-Id debe coincidir con id en el cuerpo. El ejemplo usa módulos nativos de 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**

Conserve el Buffer original antes de cualquier parser JSON. Reconstruir el cuerpo con JSON.stringify puede invalidar la firma. Guarde el secreto en el servidor y sincronice el reloj. El ejemplo valida la firma; no implementa servidor HTTP, persistencia ni procesamiento del evento.

## Confirme sin procesar dos veces

Responda con HTTP 2xx tras validar y registrar el evento de forma duradera. Use id para deduplicar. Hay hasta 6 intentos automáticos con esperas crecientes; se mantiene el ID y cada intento recibe una firma con timestamp nuevo. No se siguen redirecciones. El timeout de conexión es 5 segundos y el total es 10 segundos.

**Antes de continuar**

Para trabajo en segundo plano, registre el evento en una cola duradera antes de confirmarlo. Las instalaciones y el saldo se revisan cada minuto; las respuestas se encolan al crearse.

## Edite, renueve el secreto o reintente

Editar cambia nombre, URL, eventos y límite de saldo, conservando el secreto. Cambiar la URL cancela entregas anteriores pendientes o fallidas. Eliminar un evento cancela sus entregas pendientes o fallidas. Renovar el secreto invalida el anterior inmediatamente: configure el nuevo en el receptor. No se puede editar ni renovar durante una entrega en curso.

**Antes de continuar**

Reenviar aparece para fallos finales de un webhook activo y agenda un intento adicional, conservando ID, cuerpo y contador acumulado. Un evento repetido no debe generar otro procesamiento en el receptor.

## Avisos y retención del historial

El seguimiento revisa fallos recurrentes cada 5 minutos y avisa al titular mediante la campana, sin correo ni WhatsApp. El mismo incidente no repite avisos mientras siga abierto; las nuevas incidencias respetan un mínimo de 24 horas. El seguimiento interno depende del programador y no sustituye a una supervisión externa de disponibilidad.

**Antes de continuar**

Las llamadas API y entregas completadas o canceladas se conservan 90 días; los fallos finales, 180 días desde la última actualización. La limpieza diaria se ejecuta a las 03:15 de Brasilia. Se conservan las entregas pendientes y las claves de deduplicación.

Actualizado el 17 de octubre de 2026.

[Consultar otras guías](https://wordpane.cloud/es/documentacao/)

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