Configurare i webhook
July 30, 2026
Configura i webhook FlowAlp Pay: impostazione in dashboard, content type, retry, timeout di 20 secondi, idempotenza e conferma sicura degli ordini.
I webhook sono notifiche POST che FlowAlp Pay invia al tuo backend ogni volta che cambia lo stato di una transazione o di una subscription; anche i payout elaborati generano notifiche. Sono il modo affidabile per tenere sincronizzati gli ordini — il redirect del browser dopo il checkout non lo è.
Crea un webhook nella dashboard
Accedi alla dashboard su https://pay.flowalp.com e apri la sezione Webhooks. Per ogni webhook indichi:
- Un URL HTTPS (o indirizzo IP) raggiungibile pubblicamente che riceve ed elabora i dati
- Se le consegne fallite vanno ritentate
- Il content type del payload
| Content type | Valore dell'header | Quando sceglierlo |
|---|---|---|
| JSON | application/json | Consigliato per quasi tutti gli stack |
| Normal (PHP-Post) | application/x-www-form-urlencoded | Elaborazione classica in stile form, ad es. gestione diretta di $_POST |
Retry e timeout
Con il retry attivo, la consegna viene tentata fino a 10 volte finché il tuo endpoint non risponde con successo:
| Tentativo | Quando parte |
|---|---|
| 1 | Il prima possibile — al massimo 1–1,5 minuti dopo il primo tentativo sincrono |
| 2 | 15 minuti dopo il tentativo precedente |
| 3 | 1 ora dopo il tentativo precedente |
| 4 | 2 ore dopo il tentativo precedente |
| 5 | 4 ore dopo il tentativo precedente |
| 6–10 | Ogni 24 ore dopo il tentativo precedente |
Il tuo endpoint deve rispondere entro 20 secondi, altrimenti la richiesta va in timeout e il log mostra HTTP status 0 con un messaggio di timeout. Rispondi subito con 200 e sposta il lavoro pesante in una coda.
Impostazioni webhook delle integrazioni shop
Quando attivi un'integrazione e-commerce nella dashboard (ad esempio WooCommerce), l'integrazione registra un webhook proprio verso il tuo shop e porta con sé un'opzione di retry dedicata con intervalli di 5 minuti, 15 minuti, 1 ora, 2 ore, 4 ore e poi ogni 24 ore. Inserisci l'URL dello shop con esattezza: una discrepanza di schema come http:// al posto di https://, o una sottodirectory mancante, rompe l'elaborazione dei webhook.
Usa i webhook per confermare un checkout
- Crea il Gateway e salva il suo ID insieme al tuo
referenceId. - Ricevi il webhook al cambio di stato — vedi eventi e payload.
- Verifica la firma prima di toccare lo stato di qualsiasi ordine.
- Abbina l'evento all'ordine atteso tramite
referenceId(o l'ID del payment link nei dati dell'invoice). - Recupera la transazione via API se il tuo modello di rischio richiede una seconda fonte.
- Solo a quel punto segna l'ordine come pagato ed evadilo.
Non usare mai il solo redirect del browser alla pagina di successo come conferma del pagamento: i clienti possono chiudere il browser a metà flusso e gli URL possono essere chiamati direttamente.
Rispondi correttamente e resta idempotente
- Rispondi con uno stato
2xxentro 20 secondi; tutto il resto conta come consegna fallita e attiva i retry se abilitati. - Lo stesso evento può arrivare più volte: deduplica su ID transazione più stato prima di agire.
- Elabora gli eventi in modo asincrono e conserva un log di payload ricevuti ed esiti per gli audit.
Checklist di sicurezza
- Esponi un endpoint webhook dedicato, non una route generica.
- Servilo solo via HTTPS.
- Verifica le firme dei webhook e rifiuta quelle non valide con una risposta non-2xx.
- Non scrivere segreti o payload completi nei log applicativi generici.
Prossimo passo: studia i tipi di evento e i payload che riceverai, poi configura la verifica della firma.