SupportFast SupportFast Guida

Sviluppatori

Avviare un'automazione via webhook

Con un webhook un altro software, come Zapier, Make, il tuo gestionale o il modulo del tuo sito, fa partire un'automazione e le passa i suoi dati, che diventano variabili.

Vedi come Markdown
Video: Webhook e API per il tuo gestionale AC-34Avviare un'automazione da Zapier o Make, chiamare un'API esterna.

#A cosa serve

Un webhook è un indirizzo web a cui un altro software manda dei dati quando succede qualcosa. Ogni automazione con il trigger Webhook ha il suo indirizzo: quando ci arriva una richiesta, l'automazione parte.

  • Il modulo «Richiedi un preventivo» del tuo sito manda nome, email e telefono: l'automazione salva il contatto e lo richiama.
  • L'e-commerce manda un ordine: l'automazione scrive al cliente su WhatsApp.
  • Zapier e Make collegano centinaia di app: qualunque loro evento può far partire un'automazione.
Il tuo softwareManda una richiesta POST con i dati in JSON.
→
L'indirizzo dell'automazioneAccetta la richiesta e risponde.
→
L'automazioneParte e usa i dati come variabili {{webhook.*}}.

Prima di iniziare

  • La funzione «API e webhook» del piano.
  • Un servizio esterno che sa mandare una richiesta HTTP POST con corpo JSON.

#Ottenere l'indirizzo

  1. Scegli la fonte Webhook

    Nel Playground dell'automazione premi la scheda del trigger, il nodo di partenza. In Fonte di partenza scegli Webhook (API). Puoi farlo anche mentre crei l'automazione, nella finestra «Nuova Automazione», al passo Trigger.

  2. Genera l'indirizzo

    Premi Genera indirizzo. Compare l'indirizzo completo, unico per questa automazione, che finisce con /incoming/ e un codice. Sotto leggi le tre caratteristiche: Post, Application/json, No Auth.

  3. Copialo nel servizio esterno

    Premi Copia e incolla l'indirizzo dove il servizio esterno chiede l'URL del webhook.

#Fare la prova

La prova è obbligatoria: senza, gli eventi del webhook non avviano l'automazione e l'automazione non si pubblica. Serve anche a far conoscere alla console i campi che arriveranno.

  1. Metti in ascolto

    In Test Webhook premi Metti in ascolto. Lo stato diventa «In ascolto...».

  2. Manda la richiesta di prova

    Dal servizio esterno manda un POST all'indirizzo con /test aggiunto subito dopo il codice. Se mandi anche dei parametri, /test va prima del «?»: per esempio INDIRIZZO-DEL-WEBHOOK/test?origine=sito.

  3. Controlla cosa è arrivato

    Compare «Test ricevuto», con Dati ricevuti e Headers ricevuti. Da adesso i campi sono nel pannello delle variabili, scheda Input, fascia «Dati ricevuti dal webhook».

  4. Costruisci, salva e pubblica

    Usa le variabili nei nodi, poi premi Salva modifiche e Pubblica.

L'ascolto si spegne quando arriva la prova, quando premi Annulla ascolto, quando lasci il Playground o, se fai la prova mentre crei l'automazione, quando chiudi la finestra «Nuova Automazione». Per rifare la prova premi Rimetti in ascolto.

Dopo la prova togli /test. In produzione l'indirizzo si usa così com'è. Se in Zapier, in Make o nel tuo software resta l'indirizzo con /test, le richieste vere ricevono 404 e l'automazione non parte.

Pannello del trigger Webhook dopo la prova: indirizzo generato con Copia e Rigenera, pastiglie Post, Application/json e No Auth, e la sezione Test Webhook con Test ricevuto e i Dati ricevuti.
Dopo la prova il pannello mostra i dati e gli header ricevuti, che diventano variabili {{webhook.*}}.

#Autenticazione e header

L'indirizzo accetta richieste POST con un corpo JSON. Manda sempre l'intestazione Content-Type: application/json: senza, o con un altro tipo, il corpo non viene letto. La richiesta è accettata lo stesso, con 202, ma l'automazione parte senza i dati del corpo; arrivano solo i parametri dell'indirizzo e gli header. Una prova mandata così registra una struttura vuota.

Il codice nell'indirizzo fa da chiave: custodiscilo come una password, dallo solo ai servizi che devono usarlo, non metterlo nel codice di una pagina web e, se serve, rigeneralo.

Gli header personalizzati che mandi diventano variabili col nome in minuscolo: un header Negozio si legge con {{webhook.headers.negozio}}. Gli header standard, come host, content-type e user-agent, vengono tolti.

#Il formato dei dati

Il corpo è un oggetto JSON, al massimo 1 MB: oltre, la richiesta è rifiutata con 413 e l'automazione non parte. Ogni campo del corpo, ogni parametro dell'indirizzo (quelli dopo il «?») e ogni header personalizzato diventa una variabile {{webhook.*}}: i campi annidati si leggono col punto, gli elementi delle liste con la posizione da 0. La tabella degli Esempi mostra ogni caso.

Usa nomi di campo semplici, con lettere, cifre e «_». Nella prova manda la stessa struttura che userai davvero: il pannello delle variabili propone i campi della prova, e un campo che poi non arriva resta vuoto. Se la struttura cambia, rifai la prova con Rimetti in ascolto.

#Esempi

Al posto di INDIRIZZO-DEL-WEBHOOK incolla l'indirizzo copiato dalla console.

curl · una richiesta con un parametro e un header

curl -X POST "INDIRIZZO-DEL-WEBHOOK?origine=sito" \
  -H "Content-Type: application/json" \
  -H "Negozio: officina-rossi" \
  -d '{"nome":"Mario","cognome":"Rossi","email":"mario.rossi@esempio.it","telefono":"+39 02 1234 5678","ordine":{"numero":"A-1029","totale":149.9},"righe":[{"sku":"FILTRO-OLIO","quantita":1}]}'
Dato mandatoVariabileValore
nome{{webhook.nome}}Mario
ordine.totale{{webhook.ordine.totale}}149.9
righe, primo elemento, sku{{webhook.righe[0].sku}}FILTRO-OLIO
parametro origine{{webhook.origine}}sito
header Negozio{{webhook.headers.negozio}}officina-rossi

Con Zapier o Make. Nello scenario aggiungi il passo che manda una richiesta HTTP: in Zapier l'azione POST dell'app Webhooks by Zapier, in Make il modulo HTTP. Imposta il metodo POST, l'indirizzo copiato e i dati in formato JSON.

#La risposta

Se la richiesta è accettata e il flusso non ha il nodo Risposta Webhook, l'indirizzo risponde subito 202 e l'esecuzione parte:

JSON · la risposta predefinita

{"success": true, "message": "Webhook received"}

Per decidere tu cosa riceve chi chiama, aggiungi al flusso il nodo Risposta Webhook. Compare nel menu solo con il trigger Webhook e ha tre campi:

Stato della risposta Menu

Il codice HTTP da restituire: 200, 201, 202, 204, 400, 401, 403, 404 o 500.

Predefinito: 200 OK

Headers Chiave e valore, con variabili

Gli header da aggiungere alla risposta, con Aggiungi header.

Corpo della risposta (JSON) JSON con variabili

Il corpo da restituire, per esempio {"ok": true, "lead": "{{CRM.id}}"}. Un valore scritto solo come variabile, come "{{CRM.id}}", mantiene il suo tipo.

Con questo nodo nel flusso la risposta non è più immediata: chi chiama la aspetta per un massimo di 30 secondi. Se l'automazione non arriva al nodo in tempo, riceve la risposta predefinita, 202, e l'automazione prosegue comunque. Per questo il nodo va messo presto nel flusso, prima di Attendi, Effettua Chiamata e chiamate API lente. Se il flusso ha più nodi Risposta Webhook, vale il primo.

RichiestaRisposta
POST all'indirizzo, con JSON valido202 subito con la risposta predefinita; con il nodo Risposta Webhook, la sua risposta entro 30 secondi.
POST senza Content-Type: application/json202, ma il corpo non viene letto: vedi Autenticazione e header.
POST all'indirizzo con /test, mentre la prova è in ascolto200 con {"test": true, "data": …}, e l'ascolto si spegne.
POST all'indirizzo con /test, senza ascolto404. Premi Metti in ascolto e rimanda la richiesta.
GET all'indirizzo200 con {"success": true} se l'automazione è pronta a ricevere, altrimenti 404.
Corpo che non è JSON valido400, anche se l'indirizzo non è pronto: il corpo si controlla per primo. Rivedi virgolette, virgole e parentesi.
Corpo oltre 1 MB413. Manda meno dati, per esempio solo i campi che l'automazione usa.
Più di 60 richieste in un minuto sullo stesso indirizzo429 con {"error": "Too many requests", "retryAfter": 60} e l'header Retry-After: 60. Riprova dopo i secondi indicati.
Indirizzo non pronto o non valido404 con {"error": "Webhook not found"}. L'automazione non è Attiva o è stata eliminata, l'indirizzo è stato rigenerato, il trigger non è più Webhook, la prova non è mai stata fatta, oppure il piano non comprende «API e webhook». Controlla che l'automazione sia Attiva e usa l'indirizzo attuale.

#Limiti

  • Al massimo 60 richieste al minuto sullo stesso indirizzo, prove comprese. Il conto parte dalla prima richiesta e si azzera dopo 60 secondi. Oltre, la risposta è 429 con l'header Retry-After, e la richiesta non avvia l'automazione: rimandala dopo i secondi indicati. Ogni risposta porta anche gli header X-RateLimit-Limit e X-RateLimit-Remaining, con il limite e le richieste che restano.
  • Il corpo può pesare al massimo 1 MB: oltre, la risposta è 413.

Distribuisci le richieste nel tempo.

#Come verificare

  1. Manda una richiesta vera

    Se la risposta non è quella attesa, cercala nella tabella qui sopra.

  2. Apri l'esecuzione

    In AutomazioniDashboard, nel Log delle esecuzioni, apri la riga nuova. Nella scheda «Evento iniziale», i Dati dell'evento mostrano il corpo ricevuto.

#Rigenerare l'indirizzo

Premi Rigenera accanto all'indirizzo, poi Conferma e Rigenera. Il vecchio indirizzo smette subito di funzionare: aggiorna quello nuovo in tutti i servizi esterni che lo usano. I dati della prova restano: non serve rifarla.

Un'automazione duplicata ha un indirizzo tutto suo, da generare e provare.

#Leggi anche

Eventi di partenza (trigger)Il webhook e gli eventi interni a confronto. Chiamare un'API esternaLa strada opposta: l'automazione che chiama il tuo software. Esempi prontiUn lead da un modulo esterno, salvato nel CRM.