Webhooks · Plan Business

Webhooks de Marai en
tiempo real

Recibe POST HTTPS firmado con HMAC-SHA256 cada vez que ocurre uno de los 12 eventos de tu agenda: citas, clientes, pagos y reservas. Para integraciones a medida con tu propio stack, sin Zapier de por medio. Disponible en plan Business.

Configurar webhooks Ver eventos disponibles

12

Eventos en tiempo real

7 de citas, 2 de clientes, 2 de pagos y 1 de reservas. Filtrables uno a uno desde el panel.
HMAC-SHA256

Cada payload firmado

Cabecera X-Marai-Signature con tu clave secreta personal. Imposible falsificar peticiones.
SSRF guard

Diseñado para producción

Doble capa: URL parser + DNS pre-resolución bloquean IPs privadas y endpoints de metadatos cloud.

¿Qué son los webhooks de Marai?

Son llamadas HTTP POST automáticas que Marai envía a una URL HTTPS de tu elección cada vez que ocurre uno de los 12 eventos disponibles en la agenda (nueva cita, cancelación, pago recibido, etc.). Cada llamada incluye un cuerpo JSON firmado con HMAC-SHA256 mediante la cabecera X-Marai-Signature, lo que te permite verificar la autenticidad antes de procesarla. El sistema está diseñado fire-and-forget: si tu endpoint falla, la operación principal de Marai no se ve afectada. Disponible en plan Business.

¿Cómo configurar webhooks?

Tres pasos para conectar Marai con cualquier servicio HTTP que admita peticiones POST: tu propio backend, una función serverless, una herramienta interna o un middleware.

Activa webhooks en plan Business

Desde Ajustes > Integraciones > Webhooks (disponible en plan Business) activas el módulo y generas una clave HMAC única para tu negocio. Guárdala: Marai no vuelve a mostrarla después.

Configura URL y eventos

Indica tu URL HTTPS de destino y selecciona los eventos que quieres recibir (de los 12 disponibles). Si no eliges ninguno, Marai envía todos. Puedes ajustar la lista en cualquier momento.

Recibe POST con JSON firmado

A partir de ese momento, cada evento dispara un POST a tu URL en menos de un segundo. Verifica la firma X-Marai-Signature contra tu clave y procesa el payload. Tiempo de espera 10 s, sin reintentos automáticos.

Eventos disponibles

Doce eventos cubren todo el ciclo de vida del producto: agenda, clientes, pagos y reservas públicas. Cada uno se puede activar o desactivar individualmente.

Citas 7 eventos

appointment.created Se ha creado una nueva cita.
appointment.confirmed El cliente ha confirmado asistencia.
appointment.rescheduled Se ha cambiado la fecha u hora.
appointment.updated Se ha modificado un campo (servicio, profesional, notas).
appointment.completed La cita ha sido marcada como completada.
appointment.cancelled Se ha cancelado la cita.
appointment.noShow El cliente no ha acudido (ausencia).

Clientes 2 eventos

client.created Nuevo cliente registrado en el negocio.
client.updated Datos de cliente actualizados (teléfono, correo, notas, etc.).

Pagos 2 eventos

payment.completed Pago procesado correctamente vía Stripe.
payment.failed Pago rechazado o fallido (tarjeta, fondos, 3D Secure, etc.).

Reservas públicas 1 evento

booking.submitted Un cliente ha enviado una solicitud desde el portal de reservas público.

Estructura del payload

Cada webhook llega como POST con cuerpo JSON UTF-8 firmado. La estructura es estable y versionada implícitamente vía el campo «event».

appointment.created.json POST application/json

1{
2  "event": "appointment.created",
3  "businessId": "uuid-string",
4  "timestamp": "2026-05-07T14:32:18.420Z",
5  "data": {
6    "appointmentId": "uuid",
7    "clientId": "uuid",
8    "professionalId": "uuid",
9    "serviceId": "uuid",
10    "startTime": "2026-05-09T10:00:00.000Z",
11    "endTime": "2026-05-09T10:30:00.000Z",
12    "status": "PENDING_CONFIRMATION"
13  }
14}

Cabeceras HTTP enviadas

Content-Type application/json
User-Agent Marai-Webhooks/1
X-Marai-Signature hex(HMAC-SHA256(body, secret))
X-Marai-Event appointment.created (nombre del evento)
X-Marai-Delivery UUID único por intento de entrega

Webhooks frente a Zapier — ¿cuál escojo?

Ambas herramientas conectan Marai con el resto de tu stack, pero apuntan a perfiles distintos. Los webhooks dan control total al equipo técnico; Zapier es la opción sin código para usuarios sin desarrolladores.

Característica	Webhooks	Zapier
Tipo de usuario	Desarrollador / técnico	Sin código / negocio
Coste por evento	0 €	Plan Zapier desde 19,99 $
Latencia	< 1 s	~5-30 s
Eventos disponibles	12	12
Plan Marai necesario	Business	Pro o Business
Reintentos automáticos	No (fire-and-forget)	Sí (Zapier reintenta)
Verificación de firma	HMAC-SHA256	URL secreta

Beneficios de los webhooks

Tiempo real verdadero

Los eventos se entregan en menos de un segundo. Sin sondeo periódico ni latencia añadida.
Coste cero por evento

A diferencia de Zapier, no pagas por número de tareas. Conectas directamente con tu propia infraestructura.
Filtrable por evento

Configura el conjunto de eventos que quieres recibir. Si solo te interesa «appointment.created», ese es el único POST que verás.
No afecta tu agenda

Si tu endpoint falla, Marai registra el error pero la operación interna sigue intacta. Diseño fire-and-forget.

Seguridad por diseño

Marai trata los webhooks salientes como una superficie de ataque potencial: cada URL pasa por dos capas de validación antes de cada envío para evitar SSRF, DNS rebinding y filtraciones a redes internas. Tu endpoint nunca recibirá una llamada que no provenga del dispatcher oficial.

HTTPS obligatorio
HMAC-SHA256 firmado
SSRF guard 2 capas
Tiempo de espera 10 s
Bloqueo de metadatos en la nube (GCP/Azure/AWS)

Activar webhooks en Business

Disponible exclusivamente en plan Business. Cancelable cuando quieras desde el panel.

Ver plan Business · Automatizaciones nativas · Funcionalidades de Marai

Más integraciones: WhatsApp · Google Calendar · Stripe · Gmail · Zapier · Microsoft

Preguntas frecuentes

¿En qué plan están disponibles los webhooks?

En el plan Business (99 €/mes). Los planes Free, Starter y Pro no incluyen webhooks personalizados; para esos planes la alternativa equivalente es la integración con Zapier (en planificación, próximamente disponible para los planes Pro y Business).

¿Qué diferencia hay entre webhooks y Zapier?

Los webhooks son la opción técnica: un POST HTTPS firmado con HMAC-SHA256 que llega a tu propio backend. Sin coste por evento, latencia <1 s, sin reintentos. Zapier es la opción sin código: configuras Zaps visualmente, conectas con miles de aplicaciones y Zapier reintenta automáticamente. Los webhooks dan control total; Zapier es más rápido de configurar.

¿Cómo verifico la firma HMAC-SHA256?

En tu endpoint, calcula el HMAC-SHA256 del cuerpo de la petición usando tu clave secreta. Compáralo en tiempo constante con el valor de la cabecera X-Marai-Signature (formato hexadecimal). Si coinciden, la petición es auténtica. La documentación del panel incluye ejemplos en Node.js y Python.

¿Hay reintentos automáticos si mi endpoint falla?

No. Marai usa un diseño fire-and-forget: cada webhook se envía una sola vez con timeout de 10 segundos. Si tu endpoint devuelve un error o no responde a tiempo, Marai lo registra pero no reintenta. Si necesitas garantías de entrega, encola el webhook entrante y procésalo desde tu propio sistema con reintentos.

¿Puedo recibir solo ciertos eventos?

Sí. Desde el panel configuras una lista de eventos a los que te suscribes. Si la lista está vacía, Marai envía los 12 eventos. Si seleccionas solo los que te interesan, los demás no se envían a tu endpoint.

¿Marai admite webhooks entrantes (de otra app a Marai)?

No directamente. Marai es origen de eventos, no destino. Si necesitas que un sistema externo cree citas o clientes en Marai, la opción es la API REST oficial (autenticada con clave API en Ajustes > Integraciones) o la próxima integración con Zapier, donde Marai aparecerá también como acción.

Eventos en tiempo real

Cada payload firmado

Diseñado para producción