Webhook HTTP

El canal de webhook es el punto de entrada genérico para conectar cualquier sistema capaz de hacer un POST HTTP. Es la opción a elegir cuando no existe un canal dedicado para tu fuente.

Cuándo usarlo

• Conectar una herramienta interna (ERP, aplicación de negocio, pasarela de pago).
• Recibir eventos de una plataforma de terceros que ofrece webhooks (Stripe, Shopify, SendGrid…).
• Disparar un pipeline desde un cron externo o un pipeline de CI.

Configuración

1. Administración → Webhooks → Nueva entrada.
2. Elige el pipeline de destino.
3. betool genera una URL pública (https://platform.betool.ai/entries/webhook/<id>) y un secreto HMAC.

El secreto se usa para firmar cada carga útil: tu sistema debe calcular HMAC-SHA256(secret, body) y pasarlo en la cabecera X-Betool-Signature. Las peticiones sin una firma válida se rechazan.

Formato de la carga útil

Envías cualquier JSON que quieras. betool no restringe la estructura. La carga útil se expone al pipeline bajo webhook.payload (con sus subclaves).

Ejemplo:

curl -X POST https://platform.betool.ai/entries/webhook/abc123 \
  -H "Content-Type: application/json" \
  -H "X-Betool-Signature: $SIGNATURE" \
  -d '{
    "type": "order.created",
    "order_id": "ord_42",
    "amount_cents": 9900,
    "customer_email": "client@exemple.com"
  }'

El pipeline puede entonces conectar un agente que lea webhook.payload.customer_email y webhook.payload.amount_cents directamente.

Respuesta

Por defecto, la respuesta HTTP devuelve 202 Accepted de inmediato (pipeline lanzado en segundo plano). Si necesitas esperar el resultado del pipeline, configura el webhook en modo síncrono — la petición se bloquea hasta que el pipeline finaliza (timeout de 30s).

Seguridad

• Firma siempre tus peticiones (HMAC).
• El secreto se puede regenerar desde el panel de administración (rotación).
• Las cargas útiles se almacenan en texto plano en el historial de ejecuciones — no envíes datos que solo deban estar cifrados en tránsito.