Configurar webhooks

Un webhook envía una petición HTTP a una URL que eliges cada vez que ocurre algo en tu salón, por ejemplo cuando se crea una cita o se actualiza un cliente. Úsalo para mantener otro sistema sincronizado con Softalon.

Crear un webhook

1. 1

   Paso 1 de 4

   Abrir Webhooks

   Ve a Configuración › Desarrolladores › Webhooks y haz clic en Crear webhook.

2. 2

   Paso 2 de 4

   Introducir el destino

   Rellena la URL de destino, por ejemplo https://example.com/webhook, y opcionalmente una Descripción para reconocerlo más adelante.

3. 3

   Paso 3 de 4

   Elegir los temas

   En Temas, selecciona los eventos que quieres. La pestaña Todos los temas muestra todos los temas disponibles, y Temas seleccionados muestra los que has elegido. Tu URL solo recibe los temas que seleccionas.

4. 4

   Paso 4 de 4

   Guardar

   Haz clic en Crear webhook.

   Verás:

   Webhook creado, y el webhook aparece en la tabla con su interruptor de estado activado.

Temas

Los temas se llaman resource.action. Estos son los disponibles:

Para saber qué significa cada disparador, consulta Los disparadores de automatizaciones explicados.

Qué envía Softalon

Cada evento es una petición POST con un cuerpo JSON:

{
  "topic": "booking/appointment.created",
  "event": {
    "id": "...",
    "type": "booking/appointment.created",
    "resource": "booking/appointment",
    "resourceId": "...",
    "salonId": "...",
    "data": {
      "object": { "...": "the full object" },
      "previousAttributes": { "...": "changed fields, for updates" }
    }
  }
}

La petición tiene estas cabeceras:

Verificar la firma

Cada webhook tiene un secreto. Softalon firma el cuerpo de la petición con él mediante HMAC-SHA256 y envía el resultado en hexadecimal en X-Webhook-Signature. Calcula el mismo valor a partir del cuerpo sin procesar de la petición y compáralos. Si no coinciden, ignora la petición.

const crypto = require("crypto");

function isValid(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Para gestionar el secreto, usa los botones de la columna Secreto:

• El botón del ojo muestra el secreto completo, y el botón de copiar lo copia.
• El botón de regenerar crea un secreto nuevo al instante. El secreto anterior deja de funcionar inmediatamente, así que actualiza tu sistema al mismo tiempo.

Entregas y reintentos

• Tu URL debe responder con un código de estado 2xx en 10 segundos. Cualquier otra respuesta cuenta como un fallo.
• Una entrega fallida se reintenta, hasta 5 intentos en total. Las esperas entre intentos aumentan: unos 30 segundos, 1 minuto, 2 minutos y 4 minutos.
• Usa X-Webhook-Delivery-Id para ignorar una entrega que ya has procesado.

Cada entrega tiene uno de estos estados:

La aplicación aún no muestra un registro de entregas. Puedes consultar las entregas a través de la API en GET /v1/salons/:salonId/webhook-endpoints/:webhookEndpointId/deliveries. Consulta Crear una aplicación de API.

Editar, pausar o eliminar un webhook

• Pausar: desactiva el interruptor de la columna Estado.
• Editar: abre el menú de la fila y elige Actualizar.
• Eliminar: abre el menú de la fila y elige Eliminar.

Los webhooks solo envían mientras tu salón tiene una suscripción activa, en prueba o vencida en un plan que incluye webhooks.