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 generici.
- Innescare una pipeline da un cron esterno o da una CI.
Configurazione
- Nell'editor del modello, configura il nodo Start con un ricevitore Webhook in entrata.
- betool genera un URL pubblico (
https://platform.betool.ai/entries/webhook/<token>). - (Consigliato) Definisci un segreto HMAC nella configurazione del ricevitore.
Quando è configurato un segreto, il tuo sistema deve firmare il body grezzo di ogni richiesta — HMAC-SHA256(secret, body), in esadecimale — e passare la firma nell'header X-Webhook-Signature, nella forma sha256=<hex> o solo <hex>. Il nome dell'header e l'algoritmo (sha256, sha384, sha512) sono configurabili, ad esempio per seguire la convenzione X-Hub-Signature-256 di GitHub. Qualsiasi richiesta senza una firma valida viene quindi rifiutata (401).
Viene verificato solo questo formato: un HMAC esadecimale del body grezzo. Una firma con timestamp (t=…,v1=…) o codificata in base64 non verrà riconosciuta.
Formato del payload
Invii qualsiasi JSON. betool non vincola la struttura. Il payload viene esposto alla pipeline sotto webhook.payload (con le sue sotto-chiavi); anche gli header, il metodo e la query string sono disponibili sotto webhook.headers, webhook.method e webhook.query.
Il body viene letto in base al suo Content-Type: JSON analizzato, modulo (application/x-www-form-urlencoded) come dizionario, XML e text/* come testo grezzo, multipart/form-data come campi + file allegati (webhook.payload._files), qualsiasi altro tipo (PDF, immagine, archivio…) salvato come file. Un body compresso in gzip viene decompresso. Dimensione massima: 50 MB (413 oltre).
Esempio:
curl -X POST https://platform.betool.ai/entries/webhook/abc123 \
-H "Content-Type: application/json" \
-H "X-Webhook-Signature: sha256=$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
Due modalità di risposta (response_mode): sync (predefinita) blocca fino al risultato della pipeline e lo restituisce nella risposta; ack restituisce immediatamente un 202 Accepted dopo aver messo l'evento in una coda durevole (la pipeline viene eseguita in seguito, con nuovi tentativi) — da scegliere per i provider che vanno in timeout presto.
Chiamate GET (opzione)
Per impostazione predefinita è accettato solo POST: un GET riceve 405. Per un partner che impone una consultazione in GET ?action=…, spunta Accetta anche GET (allow_get). La query string diventa allora webhook.payload, nella stessa forma di un POST di un modulo: la pipeline non deve sapere quale metodo è stato usato. Un GET non porta body (rifiutato con 400) e non è compatibile con la firma HMAC (rifiutato con 405 finché è impostato un segreto). Un identificativo passato nella query compare nei log di accesso: preferisci POST quando il partner lo consente.
Sicurezza
- Firma le tue richieste (HMAC) non appena l'endpoint gestisce qualcosa di diverso da un test.
- Il segreto si può cambiare in qualsiasi momento nella configurazione del ricevitore (rotazione). Una volta salvato, non viene mai più mostrato: il campo indica « •••••• salvato — digita per sostituire », e Rimuovi lo cancella (la firma non viene più verificata).
- I payload sono memorizzati in chiaro nella cronologia delle esecuzioni — non inviare dati che devono essere cifrati solo in transito.