Está tardando más de lo normal. Tu conexión parece débil.
KelluDesarrolladores
Referencia interactivaOpenAPIManual UTCP

Guías

  • Inicio
  • Inicio rápido
  • Autenticación
  • Permisos
  • Paginación y errores
  • Recursos y operaciones
  • Webhooks
  • WhatsApp por webhook
  • Agentes de IA, OpenAPI y UTCP
  • Conector de IA (Claude y ChatGPT)
  • Guía: usar Kellu desde Claude y ChatGPT
  • Kellu AI connector: user guide (English)

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):

  1. 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.
  2. Elige los eventos que quieres recibir (al menos uno).
  3. 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" }
}
  • id identifica el evento y es el mismo en todos los reintentos: úsalo para no procesar dos veces el mismo evento.

  • source dice de dónde vino el cambio:

    • { "type": "app" }: desde Kellu (web, app móvil, portal, procesos automáticos). También el webhook.test.
    • { "type": "connector", "clientId": "…" }: lo hizo un asistente de IA con el conector de IA. clientId identifica 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.

  • data es delgado a propósito: el tipo de objeto, su id, 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 es whatsapp.message_requested.

Encabezados de cada envío:

EncabezadoValor
content-typeapplication/json
user-agentKellu-Webhooks/1
webhook-idEl id del evento.
webhook-timestampSegundos Unix del momento de ESTE intento.
webhook-signaturev1,<firma> (ver abajo).

Eventos

EventoCuándodata (además de object e id)Léelo con
client.createdSe creó un cliente.—GET /clients/{id}
work_order.createdSe creó un trabajo.—GET /work-orders/{id}
work_order.completedEl 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.statusGET /work-orders/{id}
visit.status_changedEl estado de una visita cambió de valor (SCHEDULED, ON_MY_WAY, IN_PROGRESS, COMPLETED).workOrderId, status, previousStatusGET /work-orders/{workOrderId}
quote.issuedUna 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, workOrderIdGET /quotes/{id}
quote.approvedSe aprobó una cotización, por el cliente (enlace o portal) o marcada por el negocio.workOrderId, versionId (puede ser null), statusGET /quotes/{id}
sale_note.issuedUna versión de una nota de venta quedó emitida. Misma regla que quote.issued.versionId, workOrderIdGET /sale-notes/{id}
sale_note.paidUna nota de venta emitida pasó a pagada porque los pagos cubren su saldo. Cerrarla sin pago o desmarcarla como incobrable no lo emite.workOrderId, statusGET /sale-notes/{id}
job_form.submittedSe 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_requestedSolo con WhatsApp por webhook activo.Ver WhatsApp por webhook—
webhook.testEvento 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:
FallaPróximo intento
11 minuto después
25 minutos después
330 minutos después
42 horas después
55 horas después
610 horas después
710 horas después
8Sin 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ódigoSignificado
TIMEOUTTu endpoint no respondió en 10 segundos.
DNSNo se pudo resolver el dominio.
TLSError en la conexión segura (certificado).
CONNECTIONNo se pudo conectar.
HTTP_ERRORTu endpoint respondió un código que no es 2xx.
REDIRECTTu endpoint respondió una redirección (3xx).
BLOCKED_ADDRESSLa URL apunta a una dirección no permitida.
SECRET_UNAVAILABLEKellu 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_DISABLEDEl endpoint se desactivó o se eliminó antes de entregar.
API_ACCESS_DISABLEDEl acceso a la API del negocio se deshabilitó.