INTEGRACIÓN
Webhooks
Recibe notificaciones en tiempo real de eventos en tu cuenta, firmadas con HMAC.
Los webhooks te avisan en el momento en que pasa algo relevante — una tarea que se finaliza, una cita que se reserva — en vez de tener que consultar la API periódicamente para ver si algo cambió.
Configuración
Da de alta un webhook desde el Backoffice (sección «Webhooks») indicando la URL de destino y a qué eventos te suscribes, o por MCP con webhooks_crear(url, eventos_suscritos, tenant=None). El secreto devuelto (para verificar la firma de cada entrega) solo se enseña esa vez — apúntalo, no se puede volver a leer después.
{
"id": 7,
"tenant_id": null,
"url": "https://tuservidor.com/webhooks/guilda",
"eventos": ["tarea.finalizada", "nota.creada"],
"secreto": "3f8a...solo-se-enseña-una-vez",
"activo": 1
}
Formato del payload
{
"id": "evt_1234",
"evento": "tarea.finalizada",
"fecha": "2026-10-10T09:30:00",
"datos": {
"tarea_id": 42,
"nombre": "Reunión de seguimiento",
"duracion_segundos": 2460
}
}
Cabeceras de cada entrega
| Cabecera | Contenido |
|---|---|
X-Guilda-Event | Nombre del evento, p. ej. tarea.finalizada. |
X-Guilda-Signature | sha256=<hex> — HMAC-SHA256 del cuerpo, ver abajo. |
X-Guilda-Signature-V2 | t=<unix>,v1=<hex> — HMAC-SHA256 de "<unix>." + cuerpo. Recomendada: comprueba que t no tenga más de 5 minutos para descartar entregas repetidas. |
X-Guilda-Timestamp | El mismo <unix> de la firma V2. |
X-Guilda-Delivery | Id de la entrega, igual en todos los reintentos del mismo evento: úsalo para descartar duplicados. |
Verificar la firma
La firma es un HMAC-SHA256 calculado sobre el cuerpo crudo tal cual se envía, usando el secreto de ese webhook como clave — mismo esquema que GitHub/Stripe, no uno propio. Recalcúlala y compárala con X-Guilda-Signature antes de procesar el evento; hazlo siempre sobre el cuerpo recibido tal cual, nunca sobre un JSON reserializado (el orden de las claves o los espacios pueden cambiar, y la firma no coincidiría aunque el contenido sea «el mismo»).
import hashlib
import hmac
def firma_valida(cuerpo_crudo: bytes, cabecera_recibida: str, secreto: str) -> bool:
esperada = "sha256=" + hmac.new(secreto.encode(), cuerpo_crudo, hashlib.sha256).hexdigest()
return hmac.compare_digest(cabecera_recibida, esperada)
Reintentos
Si tu endpoint no responde con un código 2xx (o no contesta en 10 s), la entrega se reintenta hasta 6 veces con espera creciente (inmediato, 30 s, 5 min, 30 min, 2 h, 12 h) antes de darla por fallida. Los envíos pendientes se guardan en una cola persistente: un reinicio del servidor no los pierde. La garantía es «al menos una vez», así que tu receptor debe tolerar duplicados (usa X-Guilda-Delivery). Cada intento queda registrado en el log de entregas del Backoffice, donde también puedes enviar un evento de prueba (ping) y reintentar a mano los fallidos.
Catálogo de eventos
| Evento | Se dispara cuando... |
|---|---|
tarea.finalizada | Se finaliza una tarea con duración (ver Modelos de datos). |
nota.creada | Se crea una nota — no se dispara al editarla, solo al crearla. |
cita.reservada | Se crea una reserva de Cal.diy vía citas_crear_reserva. |
correo.mensaje_nuevo | Una sincronización de correo trae mensajes nuevos (uno por sincronización con novedades, no uno por mensaje). |
tarea.creada | Se crea una tarea de la lista (payload: tarea_id, asunto, asignada_a). |
tarea.completada | Se completa una tarea de la lista, también desde el tablero o por quien la tiene asignada. |
tarea.asignada | Se asigna una tarea a un compañero del despacho (no al desasignarla). |
correo.enviado | Sale un correo por SMTP (payload: cuenta, destinatarios y asunto; nunca el cuerpo). |
nota.editada | Se edita una nota existente. |
vencimiento.presentado | Se marca como presentado un vencimiento del calendario fiscal. |
cliente.creado | Se da de alta un cliente fiscal (payload: cliente_id, nombre, nif). |
correo.sin_respuesta | Un correo con «avísame si no responde» llega a su plazo sin respuesta. |
ping | Solo al pulsar «Enviar prueba» en el Backoffice. |
db.py, sería ruido en el uso diario normal del registro de actividad.Gestión por MCP
| Tool | Descripción |
|---|---|
webhooks_listar(tenant=None) | Lista los webhooks configurados (sin el secreto). |
webhooks_crear(url, eventos_suscritos, tenant=None) | Da de alta un webhook nuevo. |
webhooks_borrar(webhook_id) | Borra un webhook (y su historial de entregas). |