Configure webhooks

I webhook notificano il tuo backend quando cambia lo stato di una transazione o di una subscription. Configurali nel merchant dashboard, sezione Webhooks.

Configurazione

• Indica un URL (o IP) raggiungibile pubblicamente in HTTPS.
• Scegli se abilitare il retry in caso di errore lato tuo.
• Scegli il content type:

• JSON (application/json) — consigliato per la maggior parte degli stack
• Normal / PHP-Post (application/x-www-form-urlencoded)

Retry e timeout

Con retry attivo, la piattaforma ritenta fino a 10 volte a intervalli crescenti (da quasi immediato fino a ritardi di 24 ore tra i tentativi successivi).

Il tuo endpoint deve rispondere entro 20 secondi. In caso di timeout, nei log compare tipicamente status 0.

Come usarli in un checkout Gateway

• Crea il Gateway e salva referenceId / id Gateway.
• Ricevi il webhook al cambio stato.
• Valida che l’evento riguardi l’ordine atteso.
• Conferma lo stato anche con un retrieve API se il tuo risk model lo richiede.
• Solo allora marca l’ordine come pagato.

Non usare il solo redirect del browser come conferma di pagamento.

Sicurezza

• Esporre solo endpoint dedicati ai webhook.
• Non loggare segreti.
• Rendi l’handler idempotente (lo stesso evento può arrivare più volte con i retry).
• Se configuri una firma/segreto webhook nel dashboard, verificala secondo le impostazioni del tuo account; in ogni caso riconcilia con lo stato API.

Passaggi successivi

• Accettare un pagamento (/docs/flowalp-pay/payments/one-time)
• Errori (/docs/flowalp-pay/api/errors)
• Checklist di go-live (/docs/flowalp-pay/testing/launch-checklist)