Documentación / Recursos Avançados
Recursos Avançados

Cómo Configurar Notificaciones (Webhooks) para Citas Vía API

Webhooks

La plataforma eAgenda permite configurar webhooks para recibir notificaciones en tiempo real sobre eventos de citas, como creación, actualización o cancelación. Este tutorial le guía a través del proceso de configuración de webhooks en el panel de eAgenda y muestra cómo implementar un servidor para procesar esas notificaciones vía API. Con ejemplos prácticos basados en payloads reales, podrá integrar notificaciones a su sistema de forma eficiente. Para más detalles, consulte la documentación oficial: eagenda.com.br.

Preparación para Configurar Webhooks

Antes de comenzar, necesitará:

  • Acceso al Panel de eAgenda: Inicie sesión en eagenda.com.br con una cuenta de administrador.
  • URL de Destino: Prepare una URL pública para recibir las notificaciones (ej.: https://suservidor.com/webhook). Para pruebas, use herramientas como Ngrok.
  • Token de Autenticación (opcional): Si es necesario, configure un token para autenticar las solicitudes (ej.: Bearer Token).
  • Herramientas para Pruebas: Utilice cURL, Postman o bibliotecas como requests (Python) para simular notificaciones.

Consejo: Su servidor debe responder con un estado HTTP 200 OK para confirmar la recepción del webhook, según lo exigido por eAgenda.

Paso a Paso: Configurando Webhooks en la Plataforma eAgenda

Siga los pasos a continuación para configurar un webhook en el panel de eAgenda. Cada etapa incluye una descripción de la pantalla correspondiente, simulando la inclusión de imágenes.

1. Acceda a la Pantalla de Integraciones Webhook

  1. Inicie sesión en el panel de eAgenda en https://eagenda.com.br.
  2. En el menú lateral a la izquierda, haga clic en Integraciones y seleccione Webhook.

Será redirigido a la pantalla de Gestión de Webhooks, donde puede visualizar webhooks existentes o agregar uno nuevo.

2. Agregue un Nuevo Webhook

  1. En la pantalla de Gestión de Webhooks, haga clic en el botón Agregar:

Se abrirá el formulario de configuración del nuevo webhook.

3. Complete los Detalles del Webhook

En el formulario, configure los campos obligatorios:

  • Tipo de Registro: Seleccione Cita para recibir notificaciones sobre eventos de citas.
  • URL: Ingrese la URL de su servidor que recibirá las notificaciones. Use {register_key} para incluir la clave de la cita, si es necesario. Ejemplo: https://suservidor.com/webhook/cita/{register\_key}
  • Encabezado de Autenticación: (Opcional) Agregue un objeto JSON con credenciales de autenticación. Ejemplo:{ "Authorization": "Bearer abc123xyz789" }
  • Eventos: Marque los eventos deseados:
    • Creación: Notifica la creación de una cita.
    • Actualización: Notifica cambios en una cita.
    • Cancelación: Notifica la cancelación de una cita.
  1. Haga clic en Guardar para activar el webhook.

El webhook estará activo y enviará notificaciones a la URL configurada cuando ocurran los eventos seleccionados.

Implementando el Webhook en la Práctica

Después de configurar el webhook, implemente un servidor para recibir y procesar las notificaciones. A continuación, se detalla el payload del webhook y se proporcionan ejemplos prácticos.

Entendiendo el Payload del Webhook

Cuando ocurre un evento de cita, eAgenda envía una solicitud POST con un payload JSON. Con base en el ejemplo proporcionado, aquí se muestra un payload para un evento de actualización de cita (estado ATTENDED):

{
  "event": "appointment.updated",
  "data": {
    "appointment_key": "191e1237-0240-4000-8ac1-60bcc5ae8701",
    "status": "ATTENDED",
    "calendar": {
      "calendar_key": "191e1237-0240-4000-85e4-6430bf42cf01",
      "calendar_name": "Agenda Médica"
    },
    "service_list": [
      {
        "service_key": "191e1237-0240-4000-81be-0e5d361a8501",
        "service_name": "Consulta Geral"
      }
    ],
    "attendees": [
      {
        "person_key": "191e1237-0240-4000-8584-d036c75a2f80",
        "name": "João Silva",
        "email": "joao.silva@example.com"
      }
    ],
    "start": {
      "dateTime": "2025-06-10T10:00:00Z",
      "timeZone": "America/Sao_Paulo"
    },
    "end": {
      "dateTime": "2025-06-10T10:30:00Z",
      "timeZone": "America/Sao_Paulo"
    }
  },
  "timestamp": "2025-06-10T10:35:00Z"
}
  • event: Identifica el tipo de evento (appointment.created, appointment.updated, appointment.canceled).
  • data: Contiene los detalles de la cita, como appointment_key, status, calendar y service_list.
  • timestamp: Fecha y hora del evento (formato ISO 8601).

Ejemplo de Servidor Webhook (Python con Flask)

Cree un servidor con Flask para procesar notificaciones de webhooks:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/agendamento/<register_key>', methods=['POST'])
def handle_webhook(register_key):
    # Verifica autenticación
    auth_header = request.headers.get('Authorization')
    expected_auth = 'Bearer abc123xyz789'
    if auth_header != expected_auth:
        return jsonify({"error": "Autenticación inválida"}), 401

    # Recibe el payload
    try:
        payload = request.get_json()
        event = payload.get('event')
        data = payload.get('data', {})
        appointment_key = data.get('appointment_key')
        status = data.get('status')
    except Exception as e:
        return jsonify({"error": f"Error en el payload: {str(e)}"}), 400

    # Procesa el evento
    if event == 'appointment.created':
        print(f"Nueva cita: {appointment_key}, Estado: {status}")
    elif event == 'appointment.updated':
        print(f"Cita actualizada: {appointment_key}, Estado: {status}")
    elif event == 'appointment.canceled':
        print(f"Cita cancelada: {appointment_key}")

    # Retorna éxito
    return jsonify({"status": "received", "message": "Notificación procesada"}), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Cómo usar:

  1. Instale Flask: pip install flask.
  2. Configure la URL del webhook en eAgenda como https://suservidor.com/webhook/agendamento/{register\_key}.
  3. Ejecute el servidor localmente o publíquelo con Ngrok para pruebas.

Este servidor valida la autenticación, procesa el payload y registra el evento. Puede ampliarlo para guardar datos en una base de datos o integrarlo con otros sistemas.

Probando el Webhook con cURL

Simule una notificación para probar el servidor, usando el payload proporcionado:

curl -X POST https://suservidor.com/webhook/agendamento/191e1237-0240-4000-8ac1-60bcc5ae8701 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer abc123xyz789" \
-d '{
  "event": "appointment.updated",
  "data": {
    "appointment_key": "191e1237-0240-4000-8ac1-60bcc5ae8701",
    "status": "ATTENDED",
    "calendar": {
      "calendar_key": "191e1237-0240-4000-85e4-6430bf42cf01",
      "calendar_name": "Agenda Médica"
    },
    "service_list": [
      {
        "service_key": "191e1237-0240-4000-81be-0e5d361a8501",
        "service_name": "Consulta Geral"
      }
    ],
    "attendees": [
      {
        "person_key": "191e1237-0240-4000-8584-d036c75a2f80",
        "name": "João Silva",
        "email": "joao.silva@example.com"
      }
    ],
    "start": {
      "dateTime": "2025-06-10T10:00:00Z",
      "timeZone": "America/Sao_Paulo"
    },
    "end": {
      "dateTime": "2025-06-10T10:30:00Z",
      "timeZone": "America/Sao_Paulo"
    }
  },
  "timestamp": "2025-06-10T10:35:00Z"
}'

Verificando el Funcionamiento

El servidor debe responder con:

{
  "status": "received",
  "message": "Notificación procesada"
}
  • Códigos de error:
    • 401 Unauthorized: Token de autenticación inválido.
    • 400 Bad Request: Payload malformado.

En el panel de eAgenda, acceda a la pantalla de Webhooks para verificar el historial de envíos. Consulte los logs del servidor para confirmar el procesamiento del payload.

Conclusión

En este tutorial, aprendió a configurar webhooks en la plataforma eAgenda para recibir notificaciones en tiempo real sobre citas y a implementar un servidor para procesarlas. Usando el payload proporcionado, puede integrar eventos como creación, actualización o cancelación de citas con sus sistemas, optimizando flujos de trabajo. Para más recursos, consulte la documentación de la API.

Contáctenos o Conozca Más

Estamos a su disposición para ayudarle. Acceda a nuestros canales oficiales:

📞 WhatsApp : Haga clic aquí para enviarnos un mensaje 🌐 Plataforma eAgenda : Conozca eAgenda 🏢 Nuestra Empresa : Mupi Systems – Soluciones Innovadoras 📧 Correo electrónico : contato@mupisystems.com.br 📚 Tutoriales y Documentación : Acceda a nuestras guías y tutoriales