Webhook di affiliazione

Un webhook di affiliazione è una notifica HTTP inviata a un altro sistema quando si verifica un evento relativo all’affiliazione, come una conversione, l’aggiornamento di una commissione o una variazione dello stato di un pagamento. Per le integrazioni correlate si possono usare callback o postback. I trigger e i payload supportati dipendono dalla piattaforma.

Terminologia: webhook, callback e postback

Questi termini si sovrappongono a seconda della piattaforma. Webhook descrive una notifica HTTP basata su eventi. Callback è un termine più ampio per indicare una risposta o una notifica inviata a un altro sistema. Nelle integrazioni di affiliazione, postback si riferisce spesso a un evento di conversione inviato dal server. La sola direzione non offre una distinzione universale.

Esempi di eventi e azioni del sistema ricevente

Sono esempi concettuali, non una garanzia che ogni piattaforma renda disponibili questi trigger. Prima di progettare il sistema ricevente, verifica il catalogo effettivo degli eventi e la versione del payload.

Webhook e polling a confronto

Il polling interroga un’API a intervalli prestabiliti per rilevare le modifiche. I webhook inviano gli eventi supportati man mano che si verificano. I webhook possono ridurre le richieste ripetute all’API, mentre il polling o la riconciliazione possono aiutare a recuperare gli stati mancanti. Un’integrazione robusta può usare entrambi, senza presumere che le notifiche siano complete e ordinate.

Esempio di notifica duplicata

Dopo un timeout, un evento di approvazione viene consegnato due volte. Il sistema ricevente riconosce lo stesso ID evento e registra una sola transizione di stato. Un rimborso successivo è un evento diverso e deve comunque essere elaborato, anche se riguarda la stessa transazione.

Per questo motivo, deduplicare tutti i webhook basandosi esclusivamente sull’ID della transazione può essere un errore. L’identità dell’evento e quella della transazione hanno scopi diversi.

Verifiche operative

Non inserire le credenziali in esempi pubblici, registra gli esiti della consegna senza raccogliere dati non necessari sui clienti e attiva avvisi in caso di errori ripetuti. Il sistema ricevente dovrebbe confermare le richieste secondo il protocollo documentato dal mittente ed elaborare in modo sicuro gli effetti finanziari. Riconcilia gli stati importanti con la piattaforma autorevole, anziché basarti solo sull’ora di arrivo delle notifiche.

Progettare un sistema ricevente per condizioni di consegna reali

Verifica quale evento avvia la notifica e se fa riferimento a una commissione registrata, approvata o pagata. Memorizza l’identificativo dell’evento e quello dell’entità pertinente, convalida la richiesta usando il metodo di autenticazione supportato dal mittente e accoda le operazioni che non possono essere completate rapidamente.

Prevedi eventi duplicati, ritardati, non riusciti e fuori sequenza. Un nuovo tentativo dovrebbe aggiornare lo stesso record, anziché pagare due volte un bonus. Se un’approvazione arriva prima che il record della vendita sia presente nel sistema locale, recupera o riconcilia lo stato mancante, invece di trattare l’ordine di arrivo come una regola aziendale.

La documentazione ufficiale dei webhook di Stripe descrive i modelli di consegna e di progettazione degli endpoint; le firme e i payload sono specifici di Stripe. Per i campi effettivi, i trigger supportati e l’autenticazione, consulta la documentazione della piattaforma di affiliazione. Prima di collegare un webhook a un’azione finanziaria, verifica le risposte agli errori e la riconciliazione.

Per le impostazioni corrispondenti di Post Affiliate Pro, consulta la documentazione sui callback dei webhook . Verifica la configurazione e i requisiti di integrazione rispetto alle regole del tuo programma.

Procedura in breve