Webhook HTTP

Il canale webhook è il punto di ingresso generico per collegare qualsiasi sistema in grado di effettuare un POST HTTP. È l'opzione da scegliere quando non esiste un canale dedicato per la tua sorgente.

Quando usarlo

• Collegare uno strumento interno (ERP, applicazione aziendale, gateway di pagamento).
• Ricevere eventi da una piattaforma di terze parti che offre webhook (Stripe, Shopify, SendGrid…).
• Innescare una pipeline da un cron job esterno o da una pipeline CI.

Configurazione

1. Amministrazione → Webhook → Nuova voce.
2. Scegli la pipeline di destinazione.
3. betool genera un URL pubblico (https://platform.betool.ai/entries/webhook/<id>) e un segreto HMAC.

Il segreto viene usato per firmare ogni payload: il tuo sistema deve calcolare HMAC-SHA256(secret, body) e passarlo nell'header X-Betool-Signature. Le richieste senza una firma valida vengono rifiutate.

Formato del payload

Invii qualsiasi JSON tu voglia. betool non vincola la struttura. Il payload viene esposto alla pipeline sotto webhook.payload (con le sue sotto-chiavi).

Esempio:

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"
  }'

La pipeline può quindi collegare un agent che legge direttamente webhook.payload.customer_email e webhook.payload.amount_cents.

Risposta

Per impostazione predefinita, la risposta HTTP restituisce immediatamente 202 Accepted (pipeline avviata in background). Se hai bisogno di attendere il risultato della pipeline, configura il webhook in modalità sincrona — la richiesta si blocca fino al completamento della pipeline (timeout di 30s).

Sicurezza

• Firma sempre le tue richieste (HMAC).
• Il segreto può essere rigenerato dal pannello di amministrazione (rotazione).
• I payload sono memorizzati in chiaro nella cronologia delle esecuzioni — non inviare dati che devono essere cifrati solo in transito.