Webhook

trigger_webhook · trigger · Triggers · Disponibile · v2.1.0

Descrizione

Avvia il workflow quando una richiesta HTTP arriva all'URL del webhook. URL pubblico generato automaticamente (path = workflow_id + token random) e mostrato nel pannello "Webhook URL" del nodo. Path custom opzionale via customPath per URL leggibili (es. /webhooks/c/stripe/event invece di /webhooks/<uuid>). Differenza con i sibling: trigger_webhook = endpoint always-on, request-response. Per sospensione mid-workflow con resume su callback vedi logic_wait_signal. Per ingest email usa trigger_imap. Per polling DB usa trigger_db_change. Per scheduled jobs usa trigger_cron. Auth modes: none (pubblico, signed token nel URL), header-token (Authorization: Bearer <token>), hmac-signature (HMAC-SHA256 del body con secret condiviso — pattern Stripe/PayPal/Slack), basic-auth (RFC 7617), jwt (verifica issuer/audience/exp). HMAC e\` raccomandato per integrazioni B2B production — il token nel URL e\` log-leak vulnerable mentre la firma HMAC valida ogni request anche se URL e\` intercettata. Response modes (responseMode): (a) immediate = 202 Accepted subito + workflow async (raccomandato per webhook esterni ad alta frequenza Stripe/SDI), (b) wait-for-workflow = aspetta il workflow e ritorna {runId, status} JSON, (c) use-respond-node = aspetta il workflow E un nodo action_webhook_respond finale decide status+body+headers (API REST custom). Features production-grade: raw body capture (per HMAC verify byte-perfect senza JSON re-serialization che spaccherebbe la firma), CORS configurabile per integrazioni browser (origin allowlist, preflight handled), anti-replay dedup su firma HMAC (cache LRU per nodeId+signature, TTL 10min — una request HMAC gia\` vista viene rifiutata, AUDIT WE-4), dedup via header Idempotency-Key (pattern Stripe: un retro del client con lo stesso Idempotency-Key entro 24h ritorna 200 {duplicate:true} senza rieseguire il workflow), rate-limit per-webhook configurabile (rateLimitPerMin, fixed-window per nodeId+IP → 429 + Retry-After oltre la soglia; 0 = disabilitato), audit on-hit (ogni hit autorizzato loggato con ip + method + SHA-256 del body, mai il payload in chiaro). Use case: (1) callback Stripe/PayPal/SDI post-pagamento con HMAC verify e branching su event type, (2) endpoint API REST custom per integrazioni vendor B2B con header-token, (3) submit form landing page (response HTML redirect post-success), (4) inbound webhook firmato HMAC con anti-replay automatico. Safety budget: token URL confrontato in modo timing-safe, anti-replay HMAC (TTL 10min, cap 10k), dedup Idempotency-Key (TTL 24h), rate-limit per-webhook (429 + Retry-After), CORS allowlist. La verifica firma/JWT e\` byte-perfect sul raw body.

⚙️ 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.
`rateLimitPerMin` Rate-limit (richieste/minuto per IP)	`number`	no	`0`	Massimo richieste al minuto accettate da uno stesso IP su questo webhook (finestra fissa). Oltre la soglia → 429 Too Many Requests + header Retry-After. 0 = nessun limite (default). Tipico: 60-120 per callback provider, più basso per form pubblici esposti a spam.

💡 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",
    "rateLimitPerMin": 0
  }
}

🔗 Nodi correlati nella stessa categoria

Pronto a usare Webhook?

Disponibile da subito in tutti i piani FlowForge. Provalo gratis senza carta di credito.

Inizia gratis Sfoglia tutti i nodi