Descrizione

Avvia il workflow quando una richiesta HTTP arriva all'URL del webhook. L'URL viene generato automaticamente e mostrato nel pannello "Webhook URL" qui sotto una volta selezionato il nodo. Supporta auth multipla, CORS, raw body, e percorsi custom. Per restituire una response personalizzata (HTML, JSON, redirect, file binario, ecc.) aggiungi un nodo "Webhook: Respond" alla fine del workflow.

⚙️ Parametri di configurazione

Campi mostrati nell’editor quando si configura il nodo. Generati direttamente dal NodeDefconfigFields.

Campo	Tipo	Required	Default	Descrizione
`method` Metodo HTTP accettato	`enum` `POSTGETPUTPATCHDELETEHEADOPTIONSANY`	si	`POST`	POST = riceve payload nel body (default per la maggioranza dei webhook). GET = solo query string (ping/test/pagine). PUT/PATCH/DELETE per REST. HEAD = solo headers (health check). OPTIONS = preflight CORS. ANY = accetta qualsiasi metodo. Solo questo metodo è accettato — gli altri ritornano 405.
`customPath` Percorso URL personalizzato	`string`	no	— tesi oppure webhook/orders	Se vuoto: usa il path auto-generato /webhooks/:workflowId/:token. Se valorizzato: il webhook è raggiungibile anche su /webhooks/c/<percorso>/:token (es. "tesi" → /webhooks/c/tesi/:token). Utile per URL brand-friendly o compatibili con sistemi che non accettano UUID nel path.
`authMode` Autenticazione richiesta	`enum` `noneheader-tokenbasic-authhmac-signaturejwt`	no	`none`	none = aperto (PROTEGGI con IP allowlist sotto). header-token = "Authorization: Bearer <token>". basic-auth = HTTP Basic standard. hmac-signature = firma HMAC del body (Stripe, GitHub, Shopify, Twilio). jwt = JSON Web Token firmato (verifica issuer/audience/exp).
`authSecret` Token / Password	`string (encrypted)`	no	—	header-token: il token segreto. basic-auth: la sola password (lo username va sotto).
`basicAuthUsername` Username (basic-auth)	`string`	no	— es. webhook-client	Username dell'header Authorization: Basic. Il client costruisce base64(user:pass).
`hmacSecret` Chiave HMAC condivisa	`string (encrypted)`	no	—	Chiave segreta del mittente. Tipicamente fornita dal provider (es. Stripe Signing Secret).
`hmacHeader` Nome header con la firma	`enum` `X-Hub-Signature-256X-Signature-SHA256X-SignatureStripe-SignatureX-Shopify-Hmac-Sha256X-Twilio-SignatureX-Webhook-Signature`	no	`X-Hub-Signature-256`	GitHub/GitLab = X-Hub-Signature-256. Stripe = Stripe-Signature. Shopify = X-Shopify-Hmac-Sha256.
`hmacAlgo` Algoritmo HMAC	`enum` `sha256sha1sha512`	no	`sha256`	sha256 = standard moderno. sha1 = legacy. sha512 = paranoico.
`jwtSecret` JWT Secret / Public Key	`string (encrypted)`	no	—	Per HS256: la chiave condivisa. Per RS256/ES256: la public key del firmatario (PEM).
`jwtAlgo` Algoritmo JWT	`enum` `HS256HS384HS512RS256RS384RS512ES256ES384`	no	`HS256`	HS = HMAC (symmetric). RS = RSA. ES = ECDSA. Auth0/Cognito usano RS256.
`jwtIssuer` Issuer atteso (opzionale)	`string`	no	— https://auth.example.com/	Se valorizzato, il claim "iss" del token DEVE matchare esattamente. Lascia vuoto per non controllare.
`jwtAudience` Audience attesa (opzionale)	`string`	no	— flowforge-api	Se valorizzato, il claim "aud" DEVE matchare. Lascia vuoto per non controllare.
`ipAllowlist` IP allowlist	`chip-list`	no	— es. 192.168.1.0/24	Lista IP/CIDR autorizzati. Vuoto = qualsiasi IP. Es. "203.0.113.42, 10.0.0.0/8".
`ignoreBots` Ignora bot	`boolean`	no	`false`	Se on: respinge richieste con User-Agent contenente "bot", "crawler", "spider", "scrape" (non è una difesa di sicurezza — è un filtro contro indicizzatori che vedono l'URL nei log).
`corsOrigin` CORS Allowed Origin	`string`	no	— * oppure https://miosito.com	Header Access-Control-Allow-Origin sulla response. Necessario se il webhook viene chiamato da browser (es. fetch() da una webapp su un altro dominio). "*" = qualsiasi origine (permissivo). Per produzione metti il dominio specifico.
`corsAllowCredentials` CORS Allow Credentials	`boolean`	no	`false`	Se on: Access-Control-Allow-Credentials: true (permette cookies cross-origin). NON usabile insieme a Origin="*".
`rawBody` Preserva raw body (per HMAC)	`boolean`	no	`false`	Se on: il body grezzo (stringa esatta dei bytes ricevuti) viene incluso nell'output del trigger come campo "rawBody". OBBLIGATORIO se vuoi rifare la validazione HMAC fuori da FlowForge — Stripe e GitHub firmano i bytes esatti, non il JSON dopo parse/serialize.
`responseMode` Come rispondere al chiamante	`enum` `immediatewait-for-workflowuse-respond-node`	no	`immediate`	immediate = 202 Accepted appena ricevuta (raccomandato per webhook esterni). wait-for-workflow = aspetta il workflow e ritorna {runId, status} JSON. use-respond-node = aspetta il workflow E usa un nodo "Webhook: Respond" alla fine per personalizzare body/status/headers (per HTML pages, redirect, ecc.).
`responseShape` Shape dell'output (modalità wait-for-workflow)	`enum` `envelopelast-step-outputall-steps-output`	no	`envelope`	envelope = {runId, status} (default). last-step-output = ritorna solo l'output dell'ultimo nodo come JSON. all-steps-output = array completo di tutti gli step. Ignorato se responseMode=immediate o use-respond-node.

💡 Esempio configurazione

Snippet JSON del nodo come compare nel workflow. I valori sono derivati daidefaultValue e dai parametri required.

{
  "id": "node-trigger_webhook-1",
  "defId": "trigger_webhook",
  "label": "Webhook",
  "config": {
    "method": "POST",
    "authMode": "none",
    "hmacHeader": "X-Hub-Signature-256",
    "hmacAlgo": "sha256",
    "jwtAlgo": "HS256",
    "ignoreBots": false,
    "corsAllowCredentials": false,
    "rawBody": false,
    "responseMode": "immediate",
    "responseShape": "envelope"
  }
}

Webhook

Descrizione

⚙️ Parametri di configurazione

💡 Esempio configurazione

🔗 Nodi correlati nella stessa categoria

Pronto a usare Webhook?