Webhook
Webhook per l'elaborazione dei pagamenti, che consentono notifiche HTTP in tempo reale per la sincronizzazione tra oltre 50 acquirer partner, automatizzando l'evasione e monitorando istantaneamente gli eventi di chargeback o l'attività del MID.
- Categoria
- Sviluppatore
- Funzionalità
- 6
- Disponibile su
- Tutti i piani
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.
Le notifiche webhook tempestive forniscono aggiornamenti in tempo reale sullo stato delle transazioni e sull'attività dei MID attraverso la nostra vasta rete di acquirenti. Questo flusso di dati istantaneo permette una rapida automazione dei processi aziendali critici e risposte immediate agli eventi.
Panoramica di Webhookpanoramica
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 3D 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 Webhookfunziona
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.
Perché Webhook è 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 gli storni consentono agli esercenti di rispondere entro i tempi stabiliti dal circuito. Gli avvisi immediati relativi ai rifiuti parziali o ai fallimenti della SCA consentono un coinvolgimento proattivo del cliente. Reagendo a questi eventi man mano che si verificano, Lei potrà migliorare i tassi di successo della ripresentazione e ridurre i costi operativi associati a fallimenti di pagamento non risolti o contestazioni che altrimenti sarebbero passate inosservate fino a una verifica manuale periodica.
Note normative per Webhook
Data privacy and payload security
Transmitting transaction data across open networks leaves no slack against data protection regulations like GDPR and PCI DSS. Notification payloads must travel exclusively over TLS-encrypted connections to prevent interception by unauthorised third parties during transit.
Cardflo enforces HTTPS URLs for all registered listener endpoints, rejecting any unencrypted destinations.
Furthermore, structured notifications exclude sensitive cardholder data, such as full primary account numbers or security codes. The gateway transmits tokenised identifiers and masked references, ensuring that the receiving server does not inadvertently bring its hosting environment into the highest tiers of PCI DSS compliance scope.
PSD2 and asynchronous strong customer authentication
Under Payment Services Directive 2, Strong Customer Authentication introduces asynchronous flows into the standard checkout process. When a transaction requires an out-of-band authentication step, such as a biometric check in a banking application, the initial request cannot return an immediate definitive success or failure status.
Event listeners are essential for capturing the final outcome of these mandated security challenges. Once the issuing bank confirms the authentication result through the acquirer partner network, the orchestration layer fires an asynchronous event.
This notification informs the merchant system that the security requirement is satisfied and the capture can proceed.
Casi d'uso di Webhookcasi 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.
Webhook in numeri
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.
Metodologia: queste cifre sono intervalli esemplificativi tratti da dati di settore pubblicati e coorti di esercenti osservate, non garanzie. I risultati effettivi dipendono dal profilo di rischio, dal mix di carte, dall'area geografica e dalla configurazione di acquisizione, e sono confermati solo con la definizione dei prezzi e i termini di approvazione.
Termini correlati
Parli con il Suo team per un'attivazione operativa sulle reti dei nostri partner di acquisizione.
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.
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 3D 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.
Funzionalità correlate.
Correlati guide.
Guarda come Cardflo si confronta.
Pronto a migliorare la Sua configurazione dei pagamenti?
Ci fornisca informazioni sulla Sua attività. La abbineremo ai partner di acquiring più idonei e al percorso corretto, solitamente entro una settimana.