Webhooks

Recibe notificaciones HTTP en tiempo real cuando ocurran eventos en BoundaryAI.

Resumen

Los webhooks le permiten recibir notificaciones en tiempo real cuando ocurren eventos en BoundaryAI. En lugar de consultar nuestra API periódicamente, su servidor recibe solicitudes HTTP POST automáticamente.

Casos de uso:

• Sincronizar contenido enviado a su almacén de datos

• Activar flujos de trabajo cuando se crean/publican encuestas

• Crear paneles en tiempo real

• Integrarse con Slack, Teams u otras herramientas

Requisitos previos

1. Acceso de administrador - Solo los administradores de la organización pueden gestionar webhooks

2. Endpoint HTTPS - La URL de su webhook debe usar HTTPS (HTTP no permitido)

3. URL pública - La URL debe ser accesible públicamente (no localhost, IPs privadas ni dominios internos)

4. Tiempo de respuesta - Su endpoint debe responder en 10 segundos

Eventos disponibles

Evento	Descripción	Cuándo se dispara
content.pushed	El contenido fue enviado vía API	Después de un /api/input/content/push o /api/input/content/push/bulk
survey.created	Se creó una nueva encuesta	Después de un /api/input/survey/create
survey.published	Se publicó una encuesta	Después de un /api/input/survey/publish
series.created	Se creó un nuevo grupo de feedback	Después de un /api/input/survey_series/create

Carga útil del webhook

{
  "event": "content.pushed",
  "timestamp": "2025-01-15T10:30:00.000000Z",
  "data": {
    "survey_series_id": 123,
    "survey_id": 456,
    "question_id": 789,
    "lines_pushed": 50,
    "api_key_id": 1
  }
}

Encabezados HTTP

Cada solicitud de webhook incluye estos encabezados:

Encabezado	Descripción	Ejemplo
X-Boundary-Signature	Firma HMAC-SHA256 para verificación	sha256=abc123...
X-Boundary-Event	El tipo de evento que disparó este webhook	content.pushed
Content-Type	Siempre JSON	application/json
User-Agent	Identifica a BoundaryAI como el remitente	BoundaryAI-Webhook/1.0

Gestión de Webhooks

Todos los endpoints de gestión de webhooks requieren autenticación JWT (no clave API).

Listar Webhooks

GET /api/webhooks
Authorization: Bearer {JWT_TOKEN}

^Respuesta

{
  "is_admin": true,
  "webhooks": [
    {
      "id": 1,
      "name": "Mi Webhook",
      "url": "https://example.com/webhook",
      "events": ["content.pushed", "survey.created"],
      "is_active": true,
      "failure_count": 0,
      "created_at": "2025-01-15T10:00:00+00:00",
      "last_triggered_at": null
    }
  ],
  "available_events": ["content.pushed", "survey.created", "survey.published", "series.created"]
}

Crear Webhook

POST /api/webhooks
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "name": "Mi Webhook",
  "url": "https://example.com/webhook",
  "events": ["content.pushed", "survey.created"]
}

^Respuesta

{
  "webhook": {
    "id": 1,
    "name": "Mi Webhook",
    "url": "https://example.com/webhook",
    "events": ["content.pushed", "survey.created"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2025-01-15T10:00:00+00:00",
    "last_triggered_at": null
  },
  "secret": "ngQCfdLY0Ykp0_OLrXlMhzPfYNo0WV1w9j4Imt1ddMM",
  "message": "Guarde el secreto ahora. No podrá verlo de nuevo."
}

⚠️ Importante: ¡Guarde el secreto inmediatamente - solo se muestra una vez!

Actualizar Webhook

PATCH /api/webhooks/{id}
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "name": "Nombre actualizado",
  "events": ["content.pushed"],
  "is_active": true
}

^Respuesta

{
  "webhook": {
    "id": 1,
    "name": "Nombre actualizado",
    "url": "https://example.com/webhook",
    "events": ["content.pushed"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2025-01-15T10:00:00+00:00",
    "last_triggered_at": null
  }
}

Webhook individual

GET /api/webhooks/{id}
Authorization: Bearer {JWT_TOKEN}

^Respuesta

{
  "webhook": {
    "id": 1,
    "name": "Mi Webhook",
    "url": "https://example.com/webhook",
    "events": ["content.pushed"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2025-01-15T10:00:00+00:00",
    "last_triggered_at": "2025-01-15T12:00:00+00:00"
  }
}

Eliminar Webhook

DELETE /api/webhooks/{id}
Authorization: Bearer {JWT_TOKEN}

^Respuesta

{
  "message": "Webhook eliminado correctamente",
  "webhook_id": 1
}

Verificación de firmas

Verifique siempre la firma para confirmar que el webhook proviene de BoundaryAI:

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# Uso en Flask:
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Boundary-Signature')
    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    event = request.headers.get('X-Boundary-Event')
    data = request.json
    # Procesar el webhook...
    return 'OK', 200

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

// Uso en Express:
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-boundary-signature'];
  if (!verifyWebhook(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.headers['x-boundary-event'];
  const data = JSON.parse(req.body);
  // Procesar el webhook...
  res.status(200).send('OK');
});

Política de reintentos

Si su endpoint falla, reintentamos con retroceso exponencial:

Intento	Retraso
1er reintento	1 minuto
2º reintento	5 minutos
3er reintento	15 minutos

Después de 10 fallos consecutivos, el webhook se desactiva automáticamente.

---

Referencia de errores

Formato de respuesta de error

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Descripción legible por humanos",
    "details": { }
  }
}

Códigos de error

Errores de autenticación (4xx)

Código	HTTP	Descripción	Solución
MISSING_AUTH	401	Falta el encabezado Authorization	Agregar Authorization: Bearer {key}
INVALID_AUTH_FORMAT	401	Encabezado malformado	Use Bearer {key} formato
INVALID_TOKEN	401	La clave no existe o tiene formato incorrecto	Verifique la clave, cree una nueva si es necesario
REVOKED_KEY	401	La clave fue revocada	Cree una nueva clave de API

Errores de permisos (4xx)

Código	HTTP	Descripción	Solución
INSUFFICIENT_PERMISSION	403	La clave carece del permiso requerido	Use una clave con el permiso correcto
FORBIDDEN	403	El recurso pertenece a otra organización	Verifique que los IDs sean correctos

Errores de recurso (4xx)

Código	HTTP	Descripción	Solución
SURVEY_SERIES_NOT_FOUND	404	El grupo de feedback no existe	Verificar survey_series_id
SURVEY_NOT_FOUND	404	La fuente de datos no existe	Verificar survey_id
QUESTION_NOT_FOUND	404	La pregunta no existe	Verificar question_id

Errores de validación (4xx)

Código	HTTP	Descripción	Solución
VALIDATION_ERROR	400	Datos de solicitud inválidos	Verifique details para campos específicos
INVALID_QUESTION_TYPE	400	Envío de texto a una pregunta no textual	Use una pregunta con accepts_text: true

Errores de tasa y cuota (4xx)

Código	HTTP	Descripción	Solución
RATE_LIMITED	429	Demasiadas solicitudes	Espere Retry-After segundos
INSUFFICIENT_APS	402	No hay suficientes puntos de análisis	Compre más APS o use clave de prueba