Webhook
I webhook forniscono notifiche in tempo reale, basate su eventi, per gli aggiornamenti critici del ciclo di vita dei pagamenti. I webhook di Cardflo consentono ai vostri sistemi di reagire istantaneamente agli stati dei pagamenti, alle contestazioni e ad altri eventi chiave.
Automatizzate i flussi di lavoro e mantenete la sincronizzazione tra la vostra piattaforma e Cardflo senza polling costante.
- Categoria
- Sviluppatore
- Funzionalità
- 10
- Disponibile su
- Tutti i piani
La panoramica
I webhook funzionano come callback HTTP asincroni che facilitano la comunicazione in tempo reale tra un gateway di pagamento e un server commerciale.
A differenza dei metodi di polling tradizionali in cui un server effettua richieste ripetitive per verificare gli aggiornamenti di stato, i webhook inviano i dati a un URL predefinito nel momento in cui si verifica un evento specifico all'interno del ciclo di vita del pagamento.
Questo meccanismo è fondamentale per la gestione di eventi non sincroni come i risultati dell'autenticazione 3-D Secure, i completamenti asincroni dei metodi di pagamento alternativi (APM) o la ricezione di un chargeback.
All'interno dello stack dei pagamenti, i webhook fungono da tessuto connettivo tra l'acquirente o il PSP e il sistema di gestione degli ordini interno (OMS) o la piattaforma di gestione delle entrate del commerciante.
Garantiscono che la logica successiva, come il blocco dell'inventario o il diritto digitale, rimanga accurata senza introdurre latenza o overhead API non necessari.
Una corretta implementazione richiede una robusta gestione dei codici di stato HTTP e dell'idempotenza per gestire potenziali tentativi di ripetizione dal server mittente, garantendo che ogni evento venga elaborato una e una sola volta.
Come funziona
Definire Endpoint ed Eventi
Un commerciante specifica un URL di destinazione all'interno del proprio ambiente per ricevere richieste POST. Seleziona trigger di eventi specifici dal ciclo di vita del pagamento, come il successo dell'autorizzazione, l'avvio del rimborso o la creazione di una contestazione.
Ciò garantisce che il suo sistema elabori solo pacchetti di dati pertinenti, riducendo il carico del server non necessario e mantenendo i punti di integrazione focalizzati e gestibili.
Trigger Evento e Payload
Quando si verifica una modifica di stato, ad esempio un cliente che completa una sfida SCA, il sistema genera un payload JSON. Questo payload contiene dati strutturati, inclusi l'ID transazione, l'ID commerciante (MID), l'importo e il tipo di evento specifico.
Il gateway tenta quindi di consegnare questi dati all'endpoint registrato.
Sicurezza e Verifica della Firma
Per prevenire l'iniezione di dati non autorizzati, il payload viene tipicamente firmato con una chiave segreta. Il server del commerciante ricostruisce la firma utilizzando il corpo della richiesta raw e la confronta con l'intestazione.
Questa verifica garantisce che i dati provengano dalla fonte attendibile e non siano stati manomessi durante il transito.
Riconoscere ed Elaborare
Il server del commerciante deve restituire tempestivamente un codice di stato 200 OK per riconoscere la ricezione. La logica interna viene quindi eseguita, come l'aggiornamento di un record di database o l'attivazione di un'e-mail automatica.
Se il server è offline o restituisce un errore, il sistema di consegna segue una pianificazione di ripetizione programmata per garantire la coerenza dei dati.
Perché è importante
Efficienza Operativa e Automazione
Affidarsi a controlli di stato manuali o a polling API periodici introduce una latenza che può degradare l'esperienza dell'utente e ritardare l'evasione. I webhook automatizzano la transizione tra l'autorizzazione del pagamento e la fornitura del servizio.
Ricevendo una notifica immediata di acquisizioni o regolamenti riusciti, le aziende possono automatizzare i flussi di lavoro di spedizione, la generazione di licenze o il provisioning degli account, riducendo la necessità di intervento manuale e minimizzando il rischio di errore umano nella gestione delle transazioni.
Mitigazione del Rischio e delle Contestazioni
Le notifiche per le richieste di recupero o i chargeback consentono ai commercianti di rispondere entro i tempi stabiliti dal circuito. Gli avvisi immediati relativi a soft decline o fallimenti SCA consentono un coinvolgimento proattivo del cliente.
Reagendo a questi eventi man mano che si verificano, i commercianti possono migliorare i tassi di successo della rappresentazione e ridurre i costi operativi associati a fallimenti di pagamento non risolti o contestazioni che altrimenti sarebbero passate inosservate fino a un audit manuale periodico.
Casi d'uso
Ciclo di Vita di Abbonamenti e SaaS
Quando un pagamento ricorrente fallisce o una carta scade, un webhook attiva una sequenza di sollecito automatizzata o sospende l'accesso dell'utente, mantenendo cicli di fatturazione accurati senza supervisione manuale.
Evasione Ordini E-commerce
Un rivenditore online utilizza i webhook per rilasciare la merce per la spedizione solo dopo aver ricevuto un evento 'capture. succeeded', impedendo la spedizione di articoli per i quali il pagamento non è stato completamente autorizzato.
Coordinamento dei Pagamenti del Marketplace
Le piattaforme che ricevono fondi possono attivare i pagamenti ai sub-commercianti solo dopo che la transazione iniziale del cliente ha raggiunto lo stato di regolato, garantendo liquidità e riducendo il rischio di annullamenti dei pagamenti.
Finalizzazione del Metodo di Pagamento Alternativo
Per metodi come bonifici bancari o schemi locali che non forniscono una conferma istantanea, i webhook notificano il sistema ore o giorni dopo quando i fondi sono confermati.
In cifre
Ritardo tipico del settore tra la registrazione di un evento nella piattaforma di acquisizione e l'invio del webhook all'endpoint del commerciante.
Benchmark di affidabilità standard per i servizi webhook quando si include la logica di ripetizione automatica e l'infrastruttura di consegna ridondante.
Osservazione del settore del miglioramento della velocità di evasione quando si passa dall'elaborazione batch periodica alle architetture webhook basate su eventi.
Termini correlati
Talk to our team about a live rollout on your acquiring stack.
Cosa ottieni con Webhook
- Consegna asincrona delle modifiche dello stato delle transazioni per migliorare le prestazioni del sistema.
- Supporto per più tipi di eventi, inclusi autorizzazione, acquisizione, rimborso e contestazione.
- Intestazioni di firma HMAC-SHA256 per una robusta verifica dell'integrità dei dati in entrata.
- Logica di ripetizione automatica con backoff esponenziale per i tentativi di consegna falliti.
- Controllo delle versioni del payload per garantire la compatibilità con l'evoluzione delle strutture dei dati nel tempo.
- Funzionalità di whitelisting IP per limitare il traffico in entrata a fonti gateway note.
- Inclusione della chiave di idempotenza per prevenire l'elaborazione duplicata dello stesso evento di pagamento.
- Log dettagliati degli eventi per il debug e l'audit delle prestazioni di consegna dei webhook all'interno della dashboard.
- Selezione granulare degli eventi per minimizzare l'utilizzo della larghezza di banda e i requisiti di elaborazione lato server.
- Funzionalità in modalità test per la convalida del comportamento dell'endpoint con scenari di pagamento simulati.
A short scoping call, then a written plan for your MIDs.
Domande su Webhook
Come dovrebbe gestire il nostro server le notifiche webhook duplicate?
È prassi standard per i gateway di pagamento impiegare un meccanismo di ripetizione se un endpoint non restituisce una risposta 200 OK entro un periodo di tempo specifico. Di conseguenza, il vostro server potrebbe ricevere lo stesso evento più volte.
Per mantenere l'integrità dei dati, dovreste implementare una logica di idempotenza. Ciò comporta tipicamente il tracciamento dell'ID evento univoco fornito nel payload e la verifica se è già stato elaborato prima di eseguire qualsiasi logica di business.
Se l'ID esiste nel vostro database, il vostro server dovrebbe ignorare l'evento ma restituire comunque un 200 OK per interrompere ulteriori tentativi.
Qual è la differenza tra il polling di un'API e l'utilizzo dei webhook?
Il polling richiede al vostro server di avviare richieste frequenti al gateway per verificare gli aggiornamenti di stato, il che è inefficiente e può portare a problemi di limitazione della frequenza o a informazioni ritardate.
I webhook invertono questo flusso, dove il gateway avvia una richiesta al vostro server solo quando si verifica un evento. Questo modello 'push' è più efficiente, riducendo il carico del server e garantendo che gli stati siano aggiornati quasi in tempo reale nella vostra infrastruttura,
il che è particolarmente importante per azioni sensibili al tempo come la consegna di contenuti digitali o la prevenzione delle frodi.
Perché la verifica della firma è necessaria per ogni richiesta webhook?
Poiché gli endpoint webhook sono URL pubblici, sono teoricamente accessibili da qualsiasi entità su Internet. Senza verifica, un attaccante potrebbe inviare un payload JSON falsificato al vostro server, indicando falsamente che un pagamento di alto valore è andato a buon fine.
Utilizzando un segreto condiviso per verificare la firma HMAC fornita nell'intestazione della richiesta, il vostro sistema può dimostrare matematicamente che il messaggio è stato inviato dal vostro PSP e che il contenuto non è stato alterato,
garantendo la sicurezza del vostro processo di evasione degli ordini.
Come gestiscono i webhook i requisiti 3-D Secure e SCA?
Durante un flusso 3-DS, la transazione spesso passa a uno stato in sospeso mentre l'utente viene reindirizzato al proprio emittente per l'autenticazione. Il risultato finale di questa autenticazione potrebbe non essere noto immediatamente.
I webhook vengono utilizzati per notificare il vostro sistema quando la sfida 3-DS è completata e la transazione viene successivamente autorizzata o rifiutata.
Ciò impedisce che il vostro checkout si blocchi e consente al vostro backend di reagire allo stato di autorizzazione finale una volta che il cliente torna dalla pagina di reindirizzamento della banca.
I webhook possono essere utilizzati per gestire i tempi di chargeback e contestazione?
Sì, i webhook sono uno strumento primario per la gestione del ciclo di vita delle contestazioni. Quando un titolare di carta avvia una richiesta di recupero o un chargeback formale con il proprio emittente, il gateway riceve questa notifica tramite i circuiti delle carte.
Viene quindi inviato un webhook al vostro sistema specificando il codice motivo, l'importo e la scadenza per la risposta.
Utilizzando questi dati in tempo reale, potete automatizzare la sospensione dell'account pertinente e notificare al vostro team di rischio di avviare immediatamente il processo di rappresentazione, aumentando la probabilità di un'inversione di contestazione riuscita.
Cosa succede se il nostro server è inattivo durante un evento webhook critico?
I sistemi webhook affidabili operano con una politica di ripetizione. Se il vostro endpoint restituisce un errore 4xx o 5xx, o non risponde entro pochi secondi, il gateway metterà in coda il messaggio per la riconsegna.
Questi tentativi di ripetizione di solito seguono un modello di backoff esponenziale, tentando la consegna più volte nel corso di minuti o ore.
Per garantire una coerenza a lungo termine, dovreste anche avere un meccanismo di fallback, come uno script di riconciliazione giornaliero che chiama l'API per trovare eventuali modifiche di stato perse, fornendo una rete di sicurezza per interruzioni prolungate.
Funzionalità correlate.
Pronto per la velocità?
Raccontaci della tua attività. Ti abbineremo ai giusti partner acquirenti e al percorso giusto, di solito entro una settimana.