Este artículo está dirigido a gestores de estudio que envían eventos de bsport a otras herramientas. Incluye cómo crear, probar, pausar y actualizar webhooks en Ajustes. Para las claves de API, consulta "Gestiona tus claves de API".

Resumen

Un webhook avisa a otra herramienta cuando ocurre algo en bsport. Cuando un cliente reserva una clase o se crea una factura, bsport envía los detalles a una dirección web que tú elijas. Tu herramienta de informes, CRM o plataforma de automatización puede reaccionar al instante, sin tener que consultar bsport una y otra vez.

Gestiona todos tus webhooks desde una sola página: Ajustes > Webhooks (dentro de Integraciones).

La página se llama Webhooks y API y tiene dos pestañas: Webhooks y API. Este artículo trata la pestaña Webhooks.

Los webhooks tienen distintas versiones:

V2 es la versión actual y la que creas.
V1 y Legacy son versiones anteriores que siguen enviando eventos hasta que las sustituyas (consulta "Webhooks antiguos: V1 y Legacy" más abajo).

Quién puede usarlo: los gestores cuyo rol tenga el permiso Webhook. Pide al administrador de tu estudio que lo active para tu rol.

Qué puedes hacer

Crear un webhook para un evento y una URL de destino.
Editar el evento o la URL de un webhook.
Enviar una prueba para comprobar que tu herramienta recibe los eventos.
Pausar un webhook y reanudarlo más tarde.
Copiar o rotar el secreto de firma de un webhook.
Sustituir webhooks antiguos (V1 y Legacy) por webhooks V2.
Filtrar la lista por Todos, Activos o Pausados.

Casos de uso habituales

Cómo enviar nuevas reservas a otra herramienta

Ve a Ajustes > Webhooks y selecciona Crear webhook.
En Evento, busca y elige booking.created.
En URL de destino, introduce la dirección de tu herramienta, por ejemplo https://example.com/webhooks/bsport.
Selecciona Crear webhook.

El webhook se activa de inmediato. Crea un webhook por evento: para seguir las reservas que se modifican o se eliminan, añade booking.updated y booking.deleted.

Cómo comprobar que tu herramienta recibe los eventos

Selecciona el icono de envío (Probar webhook) en la fila del webhook. bsport envía una entrega de muestra con datos de ejemplo a tu URL y muestra el resultado:

Resultado	Qué significa
Entregado	Tu herramienta respondió con un estado correcto.
El receptor respondió con un error	Tu herramienta recibió la muestra pero respondió con un estado de error. Se muestra el código de estado.
Sin respuesta	bsport no obtuvo respuesta: la herramienta agotó el tiempo de espera, no se pudo contactar, la URL no apunta a una dirección pública, o su certificado fue rechazado.

Si realizas pruebas con demasiada frecuencia, bsport te pedirá que esperes un minuto antes de la siguiente prueba.

Cómo pausar un webhook

Pausa un webhook para que bsport deje de enviar su evento a tu herramienta, sin eliminarlo. Su evento, URL y secreto de firma se mantienen guardados.

Úsalo mientras tu herramienta esté caída o en actualización, o después de sustituir un webhook V1 por uno V2.

Para pausarlo, desactiva el interruptor Activo en la fila del webhook (en el teléfono, selecciona Pausar webhook)

No se envía nada mientras el webhook está pausado.

Para reanudarlo, vuelve a activar el interruptor, o selecciona Reanudar webhook.

Cómo proteger tu herramienta de eventos falsos

Cada webhook tiene un Secreto de firma, que se muestra oculto salvo sus últimos 4 caracteres. Tu herramienta lo usa para comprobar que un evento realmente viene de bsport. Selecciona el icono de copiar para copiar el secreto en tu herramienta.

Para reemplazar el secreto, selecciona el icono de rotación (Rotar secreto) y confirma. El secreto actual deja de funcionar de inmediato, incluidos los reintentos. Actualiza tu herramienta con el nuevo secreto enseguida.

Cómo funciona

Configuración. Crea un webhook con un evento y una URL pública. Usa una dirección que empiece por https:// o http://. Las direcciones locales y privadas se rechazan.
Uso normal. Cada vez que ocurre el evento en bsport, bsport envía el nombre del evento, su fecha y los datos del evento a tu URL. La lista de eventos y el contenido de cada entrega están en la documentación de Webhooks (también enlazada en la parte superior derecha de la página).
Cambios. Edita el evento o la URL con el icono del lápiz (Editar webhook) y selecciona Guardar cambios.
Pausa o cambio de secreto. Pausa para detener las entregas. Rota el secreto si crees que se ha filtrado.

Eventos disponibles

La lista de eventos puede cambiar. La documentación de Webhooks siempre está actualizada y describe cada evento y lo que envía bsport. Consúltala antes de elegir un evento.

28 eventos repartidos en 11 recursos. Cada nombre de evento incluye el recurso y luego lo que ha ocurrido.

Recurso	Eventos
Reserva	`booking.created`, `booking.updated`, `booking.deleted`
Clase	`class.created`, `class.updated`
Cliente	`client.created`, `client.updated`, `client.tag_added`, `client.tag_removed`
Profesor	`teacher.created`, `teacher.updated`, `teacher.deleted`
Factura	`invoice.created`, `invoice.updated`
Cita	`appointment.created`, `appointment.updated`, `appointment.canceled`
Servicio	`service.created`, `service.updated`
Centro	`venue.created`, `venue.updated`, `venue.deleted`
Bono	`class_pass.created`, `class_pass.updated`
Bono del cliente	`client_class_pass.created`, `client_class_pass.updated`
Producto	`product.created`, `product.updated`

Comportamientos importantes

Un webhook activo por evento y URL

bsport rechaza un segundo webhook activo que envíe el mismo evento a la misma URL. Para reanudar un webhook pausado que duplicaría uno activo, pausa primero el activo.

Webhooks antiguos: V1 y Legacy

Tu lista puede mostrar webhooks antiguos junto a los V2. Un aviso amarillo cuenta los webhooks antiguos que aún envían eventos ("por actualizar"). Pronto dejarán de funcionar, así que pasa cada uno a V2.

Tipo	Dónde aparece	Qué puedes hacer
V2	Tabla Webhooks, versión V2	Probar, editar, pausar, copiar o rotar el secreto.
V1	Tabla Webhooks, versión V1	Pausar, o Actualizar a V2. Sin rotación de secreto.
Legacy	Tabla Webhooks Legacy	Actualizar a V2, o Desactivar. Sin pausa, sin secreto de firma.

Para pasar un webhook V1:

Selecciona Actualizar a V2 en su fila. Se abre el formulario con el evento V2 correspondiente y la misma URL.
Elige Qué webhook debe recibir los eventos
- Pausar V1: el nuevo webhook V2 recibe los eventos.
- Mantener V1 activo: el nuevo webhook V2 se crea pausado. Reanúdalo cuando tu herramienta esté lista.
Selecciona Crear webhook.

Para pasar un webhook Legacy: selecciona Actualizar a V2 y crea el webhook V2. El webhook Legacy sigue funcionando hasta que selecciones Desactivar.

Desactivar es definitivo. Elimina el webhook Legacy de forma permanente y su evento deja de enviarse. Para volver a recibir ese evento, crea un webhook V2.
Sin equivalente en V2. Los eventos de plan de facturación no tienen un evento V2, así que Actualizar a V2 está desactivado para ellos. Consulta la guía de migración de webhooks Legacy y la guía de migración de webhooks V1.

Quién ve qué

Cualquier persona con el permiso Webhook ve la pestaña Webhooks. La pestaña API es independiente y está limitada a propietarios y administradores. Consulta "Gestiona tus claves de API".

Preguntas frecuentes

No veo Ajustes > Webhooks. ¿Por qué?

Tu rol no tiene el permiso Webhook. Pide al administrador de tu estudio que lo añada a tu rol.

¿Puedo eliminar un webhook V2?

No. Pausarlo en su lugar. Un webhook pausado no envía nada.

¿Por qué se rechaza mi URL?

La URL debe ser pública y empezar por https:// o http://. Las direcciones locales y privadas, como localhost, se rechazan.

La prueba dice "Sin respuesta". ¿Qué debo comprobar?

Comprueba que tu herramienta esté funcionando, que la URL sea pública y que su certificado sea válido. Luego, vuelve a probar.

¿Puedo ver el secreto de firma completo?

La tabla muestra solo los últimos 4 caracteres. Usa el icono de copiar para copiar el secreto completo.

¿Por qué no puedo rotar el secreto de un webhook V1?

La rotación es solo para webhooks V2. Crea un webhook V2 para obtener un secreto rotable.

Gestiona tus webhooks