Webhooks
Un webhook es una URL de tu sistema a la que Kellu envía un POST cada vez que ocurre un evento en tu
negocio: se crea un cliente, se completa un trabajo, se paga una nota de venta… Así no necesitas
consultar la API a cada rato.
Crear un endpoint
En Configuración → API → Webhooks (dueño o Administrador):
- Ingresa la URL. Debe ser
https, en el puerto 443 y de acceso público. No se aceptan usuario ni contraseña en la URL, ni direcciones privadas o locales. - Elige los eventos que quieres recibir (al menos uno).
- Copia el secreto de firma (
whsec_…). Lo necesitas para verificar que cada mensaje viene de Kellu. Con Ver secreto lo vuelves a ver y con Generar nuevo lo reemplazas; al generar uno nuevo, el anterior deja de valer de inmediato, también para los envíos pendientes.
Máximo 10 endpoints por negocio. Con Enviar evento de prueba recibes un evento webhook.test en
ese endpoint (debe estar activo; no hace falta suscribirlo a nada más).
Forma del mensaje
Cada POST lleva un cuerpo JSON con esta forma:
{
"id": "evt_5f1c0e2a9b7d4c3e8a6f1b2c3d4e5f60",
"type": "work_order.completed",
"occurredAt": "2026-03-10T15:42:07.123Z",
"apiVersion": "v1",
"source": { "type": "app" },
"data": { "object": "work_order", "id": "cm…", "status": "COMPLETED" }
}
-
ididentifica el evento y es el mismo en todos los reintentos: úsalo para no procesar dos veces el mismo evento. -
sourcedice de dónde vino el cambio:{ "type": "app" }: desde Kellu (web, app móvil, portal, procesos automáticos). También elwebhook.test.{ "type": "connector", "clientId": "…" }: lo hizo un asistente de IA con el conector de IA.clientIdidentifica la aplicación conectada (puede ser una URL, como en Claude).
Los eventos generados antes de que existiera este campo no lo traen, tampoco en sus reintentos ni al usar Reenviar: trata su ausencia como desconocido.
-
dataes delgado a propósito: el tipo de objeto, suid, ids relacionados y el estado nuevo. Nunca nombres, teléfonos, montos ni texto libre. Para el detalle, lee el recurso con la API. La única excepción eswhatsapp.message_requested.
Encabezados de cada envío:
| Encabezado | Valor |
|---|---|
content-type | application/json |
user-agent | Kellu-Webhooks/1 |
webhook-id | El id del evento. |
webhook-timestamp | Segundos Unix del momento de ESTE intento. |
webhook-signature | v1,<firma> (ver abajo). |
Eventos
| Evento | Cuándo | data (además de object e id) | Léelo con |
|---|---|---|---|
client.created | Se creó un cliente. | — | GET /clients/{id} |
work_order.created | Se creó un trabajo. | — | GET /work-orders/{id} |
work_order.completed | El trabajo pasó a COMPLETED (todas sus visitas completadas). Reabrirlo y completarlo otra vez lo emite de nuevo; volver a guardar un trabajo ya completado, no. | status | GET /work-orders/{id} |
visit.status_changed | El estado de una visita cambió de valor (SCHEDULED, ON_MY_WAY, IN_PROGRESS, COMPLETED). | workOrderId, status, previousStatus | GET /work-orders/{workOrderId} |
quote.issued | Una versión de una cotización quedó emitida (enviada desde Kellu o marcada a mano). Una vez por versión: reenviarla, enviarla por otro canal o los recordatorios automáticos no lo emiten. | versionId, workOrderId | GET /quotes/{id} |
quote.approved | Se aprobó una cotización, por el cliente (enlace o portal) o marcada por el negocio. | workOrderId, versionId (puede ser null), status | GET /quotes/{id} |
sale_note.issued | Una versión de una nota de venta quedó emitida. Misma regla que quote.issued. | versionId, workOrderId | GET /sale-notes/{id} |
sale_note.paid | Una nota de venta emitida pasó a pagada porque los pagos cubren su saldo. Cerrarla sin pago o desmarcarla como incobrable no lo emite. | workOrderId, status | GET /sale-notes/{id} |
job_form.submitted | Se envió un informe. Si un envío se divide en un informe por equipo, sale un evento por cada informe. | workOrderId, visitId (puede ser null) | GET /work-orders/{workOrderId}/job-forms |
whatsapp.message_requested | Solo con WhatsApp por webhook activo. | Ver WhatsApp por webhook | — |
webhook.test | Evento de prueba enviado a pedido. No se puede suscribir. | — (id es el del endpoint) | — |
Ejemplos de data:
{ "object": "client", "id": "cm…" }
{ "object": "visit", "id": "cm…", "workOrderId": "cm…", "status": "IN_PROGRESS", "previousStatus": "ON_MY_WAY" }
{ "object": "quote", "id": "cm…", "workOrderId": "cm…", "versionId": "cm…", "status": "APPROVED" }
{ "object": "sale_note", "id": "cm…", "versionId": "cm…", "workOrderId": "cm…" }
{ "object": "sale_note", "id": "cm…", "workOrderId": "cm…", "status": "PAID" }
{ "object": "job_form", "id": "cm…", "workOrderId": "cm…", "visitId": "cm…" }
{ "object": "webhook_test", "id": "cm…" }
Verificar la firma
Kellu firma cada mensaje con el estándar Standard Webhooks: la
firma es un HMAC-SHA256, en base64, de {webhook-id}.{webhook-timestamp}.{cuerpo}, con el secreto
del endpoint (lo que va después de whsec_, decodificado de base64) como llave.
Verifica siempre sobre el cuerpo crudo, tal como llegó, antes de parsear el JSON: volver a serializarlo cambia los bytes y la firma deja de coincidir.
Node.js con una librería
Las librerías svix y standardwebhooks (npm) verifican la firma y la antigüedad del mensaje
(rechazan diferencias de más de 5 minutos):
import express from 'express'
import { Webhook } from 'standardwebhooks' // o: import { Webhook } from 'svix'
const app = express()
const webhook = new Webhook(process.env.KELLU_WEBHOOK_SECRET) // "whsec_…"
app.post('/webhooks/kellu', express.raw({ type: 'application/json' }), (req, res) => {
let event
try {
event = webhook.verify(req.body.toString('utf8'), req.headers)
} catch {
return res.status(400).send('firma inválida')
}
// Responde rápido y procesa después.
res.status(204).end()
handleEvent(event)
})
Node.js sin dependencias
import crypto from 'node:crypto'
function verifyKelluSignature(rawBody, headers, secret) {
const id = headers['webhook-id']
const timestamp = headers['webhook-timestamp']
const signatures = headers['webhook-signature']
if (!id || !timestamp || !signatures) return false
// Rechaza mensajes con más de 5 minutos de diferencia (protege contra reenvíos).
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
const expected = crypto
.createHmac('sha256', key)
.update(`${id}.${timestamp}.${rawBody}`)
.digest('base64')
return signatures.split(' ').some((entry) => {
const [version, signature] = entry.split(',')
return (
version === 'v1' &&
signature?.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
)
})
}
Python
import base64
import hashlib
import hmac
import time
def verify_kellu_signature(raw_body: bytes, headers: dict, secret: str) -> bool:
msg_id = headers.get("webhook-id")
timestamp = headers.get("webhook-timestamp")
signatures = headers.get("webhook-signature")
if not (msg_id and timestamp and signatures):
return False
# Rechaza mensajes con más de 5 minutos de diferencia (protege contra reenvíos).
if abs(time.time() - int(timestamp)) > 300:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = f"{msg_id}.{timestamp}.".encode() + raw_body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
return any(
entry.startswith("v1,") and hmac.compare_digest(entry[3:], expected)
for entry in signatures.split(" ")
)
En Flask, por ejemplo: verify_kellu_signature(request.get_data(), request.headers, secret) (los
encabezados de Flask no distinguen mayúsculas).
Entrega y reintentos
- Un envío es exitoso solo si tu endpoint responde 2xx en menos de 10 segundos. Las redirecciones (3xx) no se siguen y cuentan como falla. Kellu no lee el cuerpo de tu respuesta.
- Si falla, se reintenta. Son 8 intentos en total; tras la falla número:
| Falla | Próximo intento |
|---|---|
| 1 | 1 minuto después |
| 2 | 5 minutos después |
| 3 | 30 minutos después |
| 4 | 2 horas después |
| 5 | 5 horas después |
| 6 | 10 horas después |
| 7 | 10 horas después |
| 8 | Sin más intentos: la entrega queda fallida. |
- Tras el último intento no hay reenvío automático. Desde el registro de entregas del endpoint
(Configuración → API → Webhooks) puedes usar Reenviar en una entrega fallida: sale el mismo evento,
con el mismo
webhook-id. - Si tu endpoint apunta a una dirección bloqueada, la entrega falla de inmediato, sin reintentos.
Duplicados e idempotencia
La entrega es al menos una vez (at-least-once): un mismo evento puede llegar más de una vez, por
ejemplo si tu servidor procesó el mensaje pero respondió tarde. Guarda los id (webhook-id) que ya
procesaste e ignora los repetidos.
En casos raros (dos acciones simultáneas sobre el mismo recurso) pueden llegar dos eventos con id
distinto por el mismo cambio. Ante la duda, consulta el estado actual del recurso en la API.
Emisión de mejor esfuerzo: reconcilia con la API
El evento se genera después de guardar el cambio en Kellu, en el mejor esfuerzo: en casos excepcionales (por ejemplo, una caída justo después de guardar) un evento puede no generarse. Tampoco generan eventos las cargas masivas e importaciones de datos.
Si tu integración necesita estar completa (contabilidad, cobranza), no dependas solo de los webhooks:
recorre periódicamente la API (por ejemplo, GET /sale-notes?sortBy=updatedAt&order=desc) para
recuperar lo que falte. Tampoco supongas un orden de llegada: con reintentos, un evento posterior
puede llegar antes. Usa occurredAt y el estado actual del recurso.
Desactivación automática y alertas
- Si un endpoint lleva más de 5 días fallando sin ninguna entrega exitosa, Kellu lo desactiva y marca como fallidas sus entregas pendientes.
- El dueño y los Administradores reciben un aviso en la campana y por correo cuando una entrega agota sus reintentos (como máximo un aviso por endpoint por hora) y siempre que un endpoint se desactiva solo. El aviso nombra el endpoint y el tipo de evento, nunca el contenido.
- Al reactivar el endpoint vuelven a llegar los eventos nuevos; las entregas que ya fallaron no se reenvían solas.
Registro de entregas
Cada endpoint tiene su registro de entregas: evento, estado, intentos, código HTTP de tu respuesta y, si falló, la causa. El registro nunca muestra el contenido del mensaje. Los eventos se guardan 30 días.
Causas de falla:
| Código | Significado |
|---|---|
TIMEOUT | Tu endpoint no respondió en 10 segundos. |
DNS | No se pudo resolver el dominio. |
TLS | Error en la conexión segura (certificado). |
CONNECTION | No se pudo conectar. |
HTTP_ERROR | Tu endpoint respondió un código que no es 2xx. |
REDIRECT | Tu endpoint respondió una redirección (3xx). |
BLOCKED_ADDRESS | La URL apunta a una dirección no permitida. |
SECRET_UNAVAILABLE | Kellu no pudo leer el secreto del endpoint para firmar el envío. Falla de inmediato, sin reintentos, y te avisamos. Genera un secreto nuevo («Generar nuevo» en Configuración › API › Webhooks), configúralo en tu servidor y reenvía las entregas fallidas. Si no te deja generarlo, escríbenos. |
ENDPOINT_DISABLED | El endpoint se desactivó o se eliminó antes de entregar. |
API_ACCESS_DISABLED | El acceso a la API del negocio se deshabilitó. |