Webhooks: envía datos de SmoothStay a tus otras herramientas

Un webhook envía información desde SmoothStay hacia otra herramienta de forma automática, en el instante en que algo cambia. Cuando se crea, actualiza o elimina un contacto o una reservación, SmoothStay envía el registro completo a donde tú elijas.

La mayoría de los anfitriones conectan una herramienta de automatización como Zapier, Make o Activepieces. También puedes enviarlo a tu propia aplicación si tienes una.

Qué puedes hacer con ellos

Si alguna vez copiaste a mano los datos de un huésped desde SmoothStay hacia otra herramienta, los webhooks son la solución para dejar de hacerlo. No necesitas programar: conectas una herramienta de automatización una sola vez y funciona en segundo plano desde ese momento.

Algunas cosas que configuran los anfitriones:

• Haz crecer tu lista de correos automáticamente. Cuando un huésped se registra y acepta recibir marketing, agrégalo directo a Mailchimp, ConvertKit o la herramienta que uses. Tu lista para reservas directas se construye sola.

• Mantén una hoja de cálculo actualizada con cada reserva. Las nuevas reservaciones se agregan a una hoja de Google Sheets, dándote tu propia copia para contabilidad, tu contador o tus propios reportes.

• Recibe un mensaje cuando entre una reserva. Envía las nuevas reservaciones a Slack, WhatsApp o por mensaje de texto para enterarte sin tener que abrir el panel.

• Envía por mensaje de texto el código de la puerta al huésped al momento del check-in. El payload de la reservación incluye los datos de acceso, para que tu automatización los envíe justo a tiempo sin que tengas que buscar nada.

• Avisa a tu equipo de limpieza sobre una nueva estancia. Envía las fechas de check-in y check-out a lo que ya use tu equipo, sea un calendario compartido, Trello o un grupo de WhatsApp.

• Mantén sincronizado tu propio CRM. Si usas HubSpot, Airtable o un sistema propio, los contactos y las reservaciones se integran a medida que se crean.

Tú creas estos flujos de trabajo en tu herramienta de automatización (Zapier, Make, etc.). El trabajo de SmoothStay es enviar la información en el momento exacto en que cambia; lo que pase después depende de ti. Los eventos disponibles hoy cubren contactos y reservaciones, y agregaremos más conforme la plataforma crezca.

Antes de empezar

• Tu endpoint debe aceptar peticiones POST y funcionar bajo HTTPS.

• Ten lista la URL del endpoint. En la mayoría de las herramientas de automatización, esta es la URL de catch hook o webhook trigger.

Cómo configurar webhooks

1. Ve a Configuración → Integraciones → Configurar webhooks.

   

2. Agrega la URL de tu endpoint, omitiendo el prefijo https://. Nosotros lo agregamos por ti, así que pega solo la dirección en sí, por ejemplo cloud.activepieces.com/api/v1/webhooks/abc123. Solo se admiten endpoints seguros con HTTPS.

   

3. Selecciona los eventos que SmoothStay enviará a tu endpoint. Se requiere al menos uno. Cada evento envía un POST con el registro completo. Selecciona solo los eventos con los que tu flujo trabaje, para que tu endpoint no reciba tráfico innecesario. Puedes cambiar esta selección cuando quieras.

   

4. SmoothStay envía un evento de prueba para confirmar que tu endpoint responda. Los webhooks permanecen desactivados hasta que un evento de prueba tenga éxito, evitando enviar eventos en vivo a un endpoint inaccesible. Si la prueba falla, soluciona el problema en tu endpoint y envía otra prueba desde la misma pantalla. Para diagnosticar un fallo, abre la pestaña Logs, busca la entrega y haz clic en el ícono de Debug. La vista de depuración muestra el estado devuelto por tu endpoint, la respuesta sin procesar recibida y el payload exacto enviado. Compara eso con la referencia de códigos de estado más abajo para identificar la causa.

   

5. Por defecto, SmoothStay crea un secreto de webhook que se envía en el encabezado X-SmoothStay-Secret con cada webhook. Compáralo de tu lado para confirmar que la petición provenga realmente de SmoothStay. Mantenlo en privado. Recomendamos ampliamente usarlo.

   

6. Cambia el secreto cuando lo necesites. La rotación surte efecto de inmediato. Tu secreto actual deja de funcionar al instante y cada webhook enviado a partir de entonces llevará el nuevo, por lo que la verificación fallará en tu endpoint hasta que lo actualices allí. No hay un periodo de transición. Copia el nuevo secreto y actualiza tu endpoint antes de continuar.

7. Para desconectar, ve a Configuración → Integraciones → Webhooks, haz clic en los tres puntos y selecciona Desconectar. SmoothStay dejará de enviar eventos de inmediato. Desconectar es permanente: se eliminarán la configuración de tu endpoint, tu secreto y todos los registros de entrega, y tendrás que configurar el webhook desde cero para reanudarlo. Si solo deseas pausar las entregas temporalmente, desmarca todos los eventos en vez de desconectar.

   

Referencia técnica

Todo lo siguiente describe con exactitud lo que envía SmoothStay y cómo funciona la entrega. Si vas a conectar una herramienta de automatización como Zapier o Make, probablemente no lo necesites, ya que la herramienta se encarga de esto. Está disponible para quien construya directamente sobre los datos.

Eventos

Cada evento ejecuta un POST con el registro completo correspondiente.

Las actualizaciones pueden ejecutarse con más frecuencia de la esperada, sobre todo en reservaciones sincronizadas desde un PMS conectado. Diseña tu flujo para que recibir el mismo registro más de una vez no cause problemas.

Payload

El cuerpo es un objeto JSON con el registro y sus datos vinculados. No hay ningún envoltorio ni envelope, así que lee los campos directamente desde el nivel superior del cuerpo en lugar de buscar una clave data anidada. El nombre del evento llega en el encabezado X-SmoothStay-Event, no en el cuerpo.

Cuatro detalles a tener en cuenta sobre cómo se representan los valores:

• Los registros vinculados se anidan como objetos completos, no como IDs. El payload de una reservación contiene los objetos completos unit y contact integrados, para que no necesites una segunda consulta para obtener la dirección de la propiedad o el teléfono del huésped. El campo organization es la excepción y llega como una cadena de ID.

• Los enlaces de acceso se anidan bajoaccess. Una reservación incluye su propio objeto access específico para ella, y el objeto unit anidado lleva un objeto access independiente para el enlace general de la propiedad. Ambos contienen un token y un link completo.

• Los campos vacíos llegan como la cadena"null" o " ", no como elnullde JSON. Considera "null" como vacío al mapear campos en tu herramienta de automatización.

• Las fechas son cadenas ISO 8601 en UTC, por ejemplo 2026-07-12T17:15:15.604Z.

Ejemplo de cuerpo para contact.created:

{
  "uuid": "1784403540405x7499146989350725",
  "organization": "1728585128372x1186475767773138",
  "email": "guest@example.com",
  "first_name": "Henry",
  "last_name": "Dom",
  "phone": "447905279179",
  "language": "en",
  "location": "Bromley, United Kingdom",
  "method": "Imported from PMS",
  "integration_service": "Hospitable",
  "integration_service_uuid": "55805008",
  "marketing_opt_in": "no",
  "marketing_consent_date": "null",
  "created_date": "2026-07-18T14:39:00.000Z",
  "modified_date": "2026-07-18T14:39:00.000Z"
}

{
  "uuid": "1784403540405x7499146989350725",
  "organization": "1728585128372x1186475767773138",
  "email": "guest@example.com",
  "first_name": "Henry",
  "last_name": "Dom",
  "phone": "447905279179",
  "language": "en",
  "location": "Bromley, United Kingdom",
  "method": "Imported from PMS",
  "integration_service": "Hospitable",
  "integration_service_uuid": "55805008",
  "marketing_opt_in": "no",
  "marketing_consent_date": "null",
  "created_date": "2026-07-18T14:39:00.000Z",
  "modified_date": "2026-07-18T14:39:00.000Z"
}

{
  "uuid": "1784403540405x7499146989350725",
  "organization": "1728585128372x1186475767773138",
  "email": "guest@example.com",
  "first_name": "Henry",
  "last_name": "Dom",
  "phone": "447905279179",
  "language": "en",
  "location": "Bromley, United Kingdom",
  "method": "Imported from PMS",
  "integration_service": "Hospitable",
  "integration_service_uuid": "55805008",
  "marketing_opt_in": "no",
  "marketing_consent_date": "null",
  "created_date": "2026-07-18T14:39:00.000Z",
  "modified_date": "2026-07-18T14:39:00.000Z"
}

Es posible que se agreguen campos a los payloads con el tiempo a medida que SmoothStay evolucione. Agregar un campo no se considera un cambio disruptivo, por lo que tu endpoint debe ignorar los campos que no reconozca en lugar de fallar por su presencia.

Encabezados

Cada petición incluye estos encabezados:

Content-Type es application/json.

Entrega, reintentos y desactivación

Qué se considera un éxito. Cualquier código de estado 2xx. Una respuesta vacía sin código de estado también se toma como exitosa, ya que muchos endpoints confirman la recepción sin devolver un cuerpo. Responde apenas recibas la petición y realiza tu procesamiento después, ya que una respuesta lenta puede registrarse como tiempo de espera agotado (timeout) incluso si tu flujo termina con éxito.

Reintentos. SmoothStay intenta cada entrega hasta 3 veces en total, incluyendo el envío inicial.

Reintentamos fallos que puedan resolverse por sí solos: tiempos de espera agotados, límites de peticiones (429) y errores de servidor (la familia 5xx, incluyendo el rango 520 a 524 de Cloudflare).

No reintentamos fallos definitivos, ya que repetir la petición daría el mismo resultado. Estos son: una URL que ya no existe (404), una petición que tu endpoint rechaza (401, 403, 405) y un payload que tu endpoint no acepta (400, 413, 415, 422).

La columna Retries en la pestaña Logs muestra cuántos intentos tomó una entrega. Un valor de 1 significa que tuvo éxito en el primer intento.

Desactivación. Si un endpoint sigue fallando tras agotar los reintentos, SmoothStay desactiva el webhook y deja de enviar eventos. Le enviamos un correo al administrador de tu organización para avisarle y evitar que un endpoint roto pase desapercibido. Para reanudarlo, soluciona el problema en tu endpoint y envía un evento de prueba exitoso desde la pestaña Endpoint. Los eventos ocurridos mientras el webhook estuvo desactivado no se envían de forma retroactiva.

Garantías de entrega. La entrega es al menos una vez (at-least-once), no exactamente una vez, y no mantiene un orden estricto. Un evento reintentado puede llegar después de uno más nuevo, y el mismo evento puede recibirse dos veces. Dos buenas prácticas evitan problemas:

• Evita duplicados conX-SmoothStay-Delivery. Descarta cualquier ID de entrega que ya hayas procesado.

• UsaX-SmoothStay-Timestamppara resolver el orden. Cuando dos actualizaciones del mismo registro lleguen muy seguidas, la marca de tiempo más reciente representa el estado actual.

Seguridad

Cada webhook incluye un encabezado X-SmoothStay-Secret con un secreto compartido exclusivo para tu endpoint. Compáralo con tu secreto guardado mediante una comparación de texto directa y rechaza cualquier elemento que no coincida. Junto con HTTPS, que encripta la petición durante el trayecto, esto confirma que la petición provino de SmoothStay.

Se trata de un secreto compartido y no de una firma calculada, lo que significa que puedes verificarlo en cualquier herramienta de automatización con un simple paso de comparación.

Trata el secreto como cualquier otra credencial:

• Mantenlo en privado y guárdalo de forma segura.

• Sirve tu endpoint sobre HTTPS para no exponer el secreto en tránsito.

• Cámbialo si sospechas que quedó expuesto.

Qué incluye el payload. Los payloads de reservaciones contienen detalles operativos de la estancia, como los datos de wifi de la propiedad, instrucciones para abrir la puerta, el código de la cerradura inteligente, notas internas y enlaces de acceso a la guía digital. Esto es intencional: es lo que permite automatizaciones como enviar por texto al huésped su código de puerta al momento del check-in sin tener que hacer una segunda búsqueda.

Dado que casi todas las herramientas de automatización guardan el cuerpo completo de la petición en su historial de ejecuciones, conviene saber a dónde van a parar esos datos:

• Revisa qué conserva tu herramienta de destino y quién en tu cuenta tiene acceso para verlo.

• Descarta desde temprano en el flujo los campos que tu proceso no utilice.

• Ten cuidado al reenviar payloads sin procesar hacia destinos compartidos, como canales de chat de tu equipo o formatos de hojas de cálculo abiertas.

Resolución de problemas

Abre la pestaña Logs y haz clic en el ícono de Debug en una entrega para ver el estado devuelto por tu endpoint, su respuesta sin procesar y el payload exacto que enviamos. Aquí tienes algunos ejemplos comunes:

Si una entrega aparece como exitosa de nuestro lado pero no ocurre nada en tu herramienta, asegúrate de que el flujo de destino esté publicado y activado. Muchas herramientas de automatización aceptan peticiones en flujos en borrador sin llegar a ejecutarlos.

¿Necesitas ayuda?

Escríbenos a hello@smoothstay.io con el ID de entrega de la pestaña Logs y lo revisaremos de nuestro lado.