Entorno de PRE: solo datos de prueba. Los correos solo llegan al equipo y los cobros son de prueba.
Guilda WorkDevelopers

INTEGRACIÓN

Webhooks

Recibe notificaciones en tiempo real de eventos en tu cuenta, firmadas con HMAC.

HMAC-SHA256 cola persistente 6 intentos

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.

json
{
  "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

json
{
  "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

CabeceraContenido
X-Guilda-EventNombre del evento, p. ej. tarea.finalizada.
X-Guilda-Signaturesha256=<hex> — HMAC-SHA256 del cuerpo, ver abajo.
X-Guilda-Signature-V2t=<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-TimestampEl mismo <unix> de la firma V2.
X-Guilda-DeliveryId 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»).

python
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

EventoSe dispara cuando...
tarea.finalizadaSe finaliza una tarea con duración (ver Modelos de datos).
nota.creadaSe crea una nota — no se dispara al editarla, solo al crearla.
cita.reservadaSe crea una reserva de Cal.diy vía citas_crear_reserva.
correo.mensaje_nuevoUna sincronización de correo trae mensajes nuevos (uno por sincronización con novedades, no uno por mensaje).
tarea.creadaSe crea una tarea de la lista (payload: tarea_id, asunto, asignada_a).
tarea.completadaSe completa una tarea de la lista, también desde el tablero o por quien la tiene asignada.
tarea.asignadaSe asigna una tarea a un compañero del despacho (no al desasignarla).
correo.enviadoSale un correo por SMTP (payload: cuenta, destinatarios y asunto; nunca el cuerpo).
nota.editadaSe edita una nota existente.
vencimiento.presentadoSe marca como presentado un vencimiento del calendario fiscal.
cliente.creadoSe da de alta un cliente fiscal (payload: cliente_id, nombre, nif).
correo.sin_respuestaUn correo con «avísame si no responde» llega a su plazo sin respuesta.
pingSolo al pulsar «Enviar prueba» en el Backoffice.
Solo estos eventos de negocio concretos emiten un webhook — no hay un evento por cada escritura de db.py, sería ruido en el uso diario normal del registro de actividad.

Gestión por MCP

ToolDescripció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).