La API y las integraciones a medida
Webhooks: que GuauKit te avise
Actualizado el 5 de octubre de 2026
Un webhook es una dirección tuya a la que GuauKit hace una llamada cuando pasa algo. Se dan de alta con una dirección y la lista de eventos que te interesan, y al crearlo se devuelve un secreto que se muestra una sola vez y sirve para comprobar que la llamada es auténtica.
Se dan de alta en Ajustes → Integraciones → Webhooks: pegas la dirección, marcas los avisos que te interesan y GuauKit te enseña el secreto una sola vez —cópialo antes de cerrar—. Cada webhook se puede pausar, eliminar y probar: el botón Probar manda un aviso de verdad, con su firma, y te dice si tu servidor lo aceptó.
«Una sola vez» quiere decir una sola vez. El secreto no sale por ninguna puerta salvo la del alta. Si perdiste el tuyo, la salida es crear uno nuevo y dar de baja el anterior — no hay forma de volver a leerlo, y es a propósito.
Los diez avisos, y cuándo salen:
| Evento | Cuándo se dispara |
|---|---|
appointment.created | Se crea una cita, en la agenda o desde el portal |
appointment.updated | Se reprograma una cita: el aviso lleva la hora nueva y la anterior |
appointment.status_changed | Cambia el estado de una cita (confirmada, en curso, finalizada…) |
patient.created | Se da de alta una mascota |
patient.updated | Se modifica su ficha |
client.created | Se da de alta un cliente |
invoice.created | Se emite una factura, tanto en Facturación como en el TPV |
invoice.paid | Una pasarela de pago confirma el cobro completo (Stripe, PayPal, Redsys o Square) |
prescription.created | Se prescribe un medicamento |
vaccination.recorded | Se registra una vacuna |
Qué contiene cada aviso. Lo justo para identificar el objeto y actuar: los identificadores, los nombres y los importes. No salen las notas internas, ni las condiciones de alerta, ni el motivo de un veto: un webhook es una puerta hacia fuera de tu entidad.
El envío solo va a los webhooks activos de tu entidad, admite el comodín * para suscribirse a todo, y un fallo de tu servidor no interrumpe nada dentro de GuauKit.
Si tu servidor falla, el aviso se reintenta
Un aviso que no llega no se pierde. GuauKit lo vuelve a intentar cuatro veces más, espaciándolas: al minuto, a los 5 minutos, a los 30 y a las 2 horas. Cinco intentos en total, repartidos en unas dos horas y media.
La forma no es casual: los cortes de verdad son o de segundos —un despliegue, un reinicio— o de horas —un servidor caído de madrugada—. Cinco intentos seguidos en un minuto no cubren lo segundo, y esperar dos horas desde el principio no cubre lo primero.
No todo se reintenta. Si tu servidor contesta un 4xx —«lo que me mandas está mal», «esa dirección no existe»—, GuauKit no insiste: repetirlo cinco veces no lo arregla y solo machaca a un servidor que ya ha dicho que no. Las dos excepciones son 408 y 429, que literalmente significan «inténtalo otra vez». Un 5xx, un tiempo agotado o un fallo de conexión sí se reintentan.
Prepárate para recibir el mismo aviso dos veces. Si tu servidor procesa la llamada pero se cae antes de contestar, para GuauKit ha fallado y volverá a mandarlo. Por eso cada envío lleva la cabecera
X-Webhook-Deliverycon un identificador que no cambia entre reintentos: guárdalo y descarta el que ya hayas procesado. La cabeceraX-Webhook-Attemptte dice por cuál va (1 es el original).
El cuerpo es idéntico byte a byte en todos los intentos, así que la firma también. Y el
timestampdel sobre sigue siendo el del momento en que pasó lo que se avisa, no el del reintento.
El historial de envíos
Cada webhook tiene un botón Ver envíos con lo que se le ha mandado en los últimos 30 días: qué aviso era, cuándo, en qué quedó y por qué.
| Estado | Qué significa |
|---|---|
| Entregado | Tu servidor contestó correctamente |
| Esperando reintento | Falló y hay otro intento programado; la fila dice a qué hora |
| Enviando | Está saliendo ahora mismo |
| Sin entregar | Se agotaron los cinco intentos, o fue un error que no se reintenta |
Los que no se entregaron llevan un botón Reenviar: lo mandas a mano en cuanto tengas arreglado tu servidor, sin esperar a nada. Sirve también para los que ya se dieron por perdidos, que es el caso que más pasa —te enteras al día siguiente—.
Además, cada webhook avisa en rojo de cuántos avisos tiene esperando o sin entregar. Es lo primero que hay que mirar cuando «no llega nada».