Webhooks

Descripción

Los webhooks te permiten recibir notificaciones HTTP POST cuando ocurren eventos en tu cuenta de AgendaPro (por ejemplo, cuando se crea una reserva o se actualiza un cliente).

Configuración

Puedes registrar y administrar webhooks desde Configuraciones > Integraciones en tu cuenta de AgendaPro.

Al crear un webhook necesitas:

• URL: el endpoint que recibirá las notificaciones (debe aceptar POST).
• Eventos: los tipos de eventos que quieres recibir.

Eventos disponibles

Patrones wildcard:

Formato del payload

Cada notificación se envía como un POST con un JSON body:

{
  "event": "booking.created",
  "timestamp": "2026-03-27T14:30:00Z",
  "data": {
    "id": 12345,
    "start_time": "2026-03-28T10:00:00-03:00",
    "end_time": "2026-03-28T10:30:00-03:00",
    "service_id": 10,
    "client_id": 42,
    "location_id": 1
  }
}

Verificación de firma (HMAC-SHA256)

Cada webhook tiene un secret único que se muestra solo una vez al crearlo. Usa este secret para verificar que las notificaciones provienen de AgendaPro.

Cada request incluye un header X-Webhook-Signature con la firma HMAC-SHA256 del body:

# Ruby
expected = OpenSSL::HMAC.hexdigest('SHA256', webhook_secret, request.raw_post)
if expected == request.headers['X-Webhook-Signature']
  # Notificación verificada
end

// Node.js
const crypto = require('crypto');
const expected = crypto.createHmac('sha256', webhookSecret)
  .update(rawBody)
  .digest('hex');
if (expected === req.headers['x-webhook-signature']) {
  // Notificación verificada
}

# Python
import hmac, hashlib
expected = hmac.new(webhook_secret.encode(), request.body, hashlib.sha256).hexdigest()
if expected == request.headers.get('X-Webhook-Signature'):
    # Notificación verificada

Reintentos

Si tu endpoint no responde con un status 2xx, AgendaPro reintentará la entrega con backoff exponencial.

Después de múltiples intentos fallidos, el webhook se desactiva automáticamente. Puedes reactivarlo desde la configuración.

Buenas prácticas

• Responde rápido: retorna 200 OK lo antes posible. Procesa el evento de forma asíncrona si necesitas hacer trabajo pesado.
• Verifica la firma: siempre valida el header X-Webhook-Signature para asegurar que la notificación es legítima.
• Maneja duplicados: en casos excepcionales, un evento podría entregarse más de una vez. Usa el id del recurso para idempotencia.