Integrazione Webhook

Questo documento spiega come funzionano i webhook in uscita del plugin ADP Car Market Hub, come configurarli in modo sicuro, come un sistema ricevente dovrebbe convalidare i payload e cosa aspettarsi a livello operativo. Copre inoltre le limitazioni dell'attuale implementazione, in modo da poter progettare le integrazioni tenendone conto.

Quando utilizzare questo documento

Utilizza questo documento se stai:

• Connettendo il plugin a un CRM, a uno strumento di instradamento dei lead, a un servizio di notifica o a una piattaforma di automazione dei flussi di lavoro.
• Sviluppando o gestendo l'endpoint ricevente che il plugin deve chiamare.
• Esaminando il livello di sicurezza di un'integrazione tramite webhook.
• Risolvendo i problemi di un ricevitore che non sembra venire chiamato o che rifiuta i payload.

Il pubblico di riferimento è un integratore o uno sviluppatore che lavora sul sistema ricevente, insieme all'amministratore di WordPress che configura il plugin.

Panoramica

Un webhook è una richiesta HTTP in uscita che il plugin invia a un URL di tua scelta quando si verifica un evento specifico sul sito WordPress. Il plugin invia un documento JSON che descrive l'evento; il sistema ricevente lo elabora come desidera (creando un ticket nel CRM, pubblicando un messaggio in chat, aggiungendo dati a un foglio di calcolo, instradando un lead e così via).

Il plugin attualmente espone due eventi:

• new_lead — attivato quando un visitatore invia il modulo di contatto su una pagina di un veicolo e viene salvato un lead.
• new_import — attivato quando un veicolo viene importato o aggiornato dall'importatore.

Nota sul comportamento attuale: Nella versione attuale del plugin viene effettivamente inviato solo new_import. Il percorso per new_lead è predisposto (l'URL di destinazione, il segreto e la firma funzionano tutti) ma il suo trigger non è attivo nel codice attuale, quindi un URL new_lead configurato non riceverà ancora richieste. Nel frattempo, utilizza le email dei lead integrate per le notifiche dei lead e configura new_lead fin da ora se desideri che il ricevitore sia pronto per quando verrà attivato.

Ogni evento ha il proprio URL di destinazione configurabile. È possibile configurare un unico segreto condiviso per firmare ogni payload con HMAC-SHA256, in modo che il ricevitore possa verificare che la richiesta provenga effettivamente dal plugin.

I webhook sono opzionali. Se non viene configurato un URL di destinazione, non viene inviata alcuna richiesta per quell'evento.

Requisiti preliminari

Prima di configurare i webhook, prepara:

• Un endpoint ricevente che accetti una richiesta HTTPS POST con un corpo JSON. L'uso di HTTPS è fortemente raccomandato; un endpoint HTTP espone il payload durante il transito.
• La conoscenza di come il ricevitore risponde agli errori, in modo che il comportamento di riprovo descritto di seguito sia coerente con la tua configurazione.
• Un valore segreto condiviso da poter configurare sia nel plugin che nel ricevitore (richiesto solo se si desidera la verifica della firma — fortemente raccomandato).
• Accesso come amministratore di WordPress sul sito in cui è eseguito il plugin.

Istruzioni passo dopo passo

1. Decidi quali eventi inoltrare. Puoi configurare uno o entrambi tra new_lead e new_import. Lascia vuoto l'URL di destinazione per disabilitare quell'evento.
2. Scegli un segreto condiviso. Usa una stringa lunga e casuale (ad esempio una password generata dal tuo gestore di password). Mantienila riservata — non deve mai essere pubblicata.
3. Apri le impostazioni del plugin. Naviga su Car Market Hub → Leads. La sezione Webhooks nella scheda Leads contiene i campi New lead webhook URL, New import webhook URL e Webhook secret. Verifica l'esatta posizione nella versione attuale del plugin, poiché il raggruppamento dell'interfaccia utente può evolvere tra le versioni.
4. Configura gli URL. Incolla gli URL di ricezione nei campi corrispondenti. Il plugin convalida che il valore sia un URL sintatticamente corretto e salta l'invio se è mancante o non valido.
5. Configura il segreto. Incolla il segreto condiviso nel campo Webhook secret. Configura lo stesso valore nel ricevitore.
6. Salva e avvia un test. Salva le impostazioni, quindi attiva un evento reale: - Per new_lead: invia il modulo dei lead nella pagina di dettaglio di un veicolo da una finestra di navigazione in incognito. - For new_import: esegui l'importatore (manualmente o attendi la successiva esecuzione pianificata) in modo che almeno un veicolo venga inserito o aggiornato.
7. Conferma la ricezione. Controlla i log del ricevitore per confermare che la richiesta sia arrivata e che la firma sia stata verificata con successo. Se qualcosa non va, consulta la sezione Risoluzione dei problemi di seguito.

Riferimento di configurazione

Le chiavi di opzione corrispondenti utilizzate internamente dal plugin sono documentate in Option Keys and Settings Storage e Webhook Event Reference.

Formato della richiesta

Il plugin invia ciascun evento come una richiesta HTTPS POST con un corpo JSON e i seguenti header:

• Content-Type: application/json
• X-AS24CI-Signature: <hex> — presente solo quando è configurato un segreto per il webhook. Il valore è l'HMAC-SHA256 del corpo grezzo della richiesta, utilizzando il segreto configurato come chiave, codificato come stringa esadecimale minuscola.

L'insieme esatto dei campi nel corpo JSON può evolvere tra le versioni del plugin. Il riferimento per la versione attuale è Webhook Event Reference. Entrambi gli eventi includono come minimo:

• event — il nome dell'evento (new_lead o new_import).
• timestamp — un timestamp ISO-8601 in UTC di quando l'evento è stato preparato.
• Un identificatore per l'oggetto WordPress correlato (ID del lead per new_lead, ID dell'articolo e Listing ID per new_import).
• Un oggetto data con un piccolo insieme di campi riassuntivi sull'evento (campi base del lead per new_lead; campi base del veicolo per new_import).

I ricevitori dovrebbero trattare i campi sconosciuti come aggiunte compatibili con le versioni successive e ignorarli anziché rifiutare il payload. Verifica l'insieme di campi attuale rispetto al documento di riferimento prima di pubblicare la tua integrazione.

Convalida delle richieste in arrivo

Quando è configurato un segreto per il webhook, il ricevitore dovrebbe sempre verificare la firma prima di considerare attendibile il payload. La regola di verifica è:

1. Leggi il corpo grezzo della richiesta prima di qualsiasi parsing JSON (il parsing e la successiva riserializzazione possono modificare l'ordine dei byte o gli spazi vuoti e compromettere la firma).
2. Calcola HMAC-SHA256(raw_body, shared_secret) e codifica il risultato come stringa esadecimale minuscola.
3. Confrontalo con il valore dell'header X-AS24CI-Signature utilizzando un confronto a tempo costante (la maggior parte dei linguaggi lo fornisce come hash_equals, crypto.timingSafeEqual, hmac.compare_digest o simili).
4. Rifiuta la richiesta con 401 se la firma è mancante o non corrisponde.

Ulteriori controlli difensivi che il ricevitore dovrebbe considerare:

• Rifiutare HTTP. Accetta solo richieste HTTPS sul ricevitore.
• Inserire in whitelist l'IP di origine del sito WordPress a livello di rete o di applicazione, in aggiunta al controllo della firma.
• Idempotenza. Lo stesso evento logico potrebbe essere recapitato più di una volta (vedi Comportamento di recapito di seguito). Utilizza l'ID del lead, l'ID dell'articolo, il Listing ID o un hash del payload per eliminare i duplicati sul lato ricevitore.
• Finestra temporale del timestamp. Rifiuta le richieste il cui timestamp è molto indietro nel passato o nel futuro per limitare l'efficacia dei payload riprodotti. Pochi minuti di sfasamento dell'orologio su entrambi i lati sono normali.
• Tolleranza dello schema. Tratta i campi aggiuntivi come compatibili con le versioni successive e i nomi di eventi sconosciuti come qualcosa da registrare nei log anziché come causa di crash.
• Limite di dimensione del corpo. Limita la dimensione massima del corpo sul ricevitore per proteggerti da input non validi.

Se non è configurato alcun segreto, il ricevitore non ha modo di verificare che la richiesta provenga effettivamente dal plugin; configura un segreto a meno che il percorso di rete non sia completamente privato e attendibile.

Comportamento di recapito

L'attuale implementazione presenta le seguenti caratteristiche di recapito. Verifica questi comportamenti nella versione attuale del plugin prima di fare affidamento su di essi.

• Il primo tentativo è di tipo "invia e dimentica" (fire-and-forget). Quando viene attivato un evento, il plugin invia il primo recapito come richiesta HTTP POST non bloccante. Non attende la risposta del ricevitore e non interpreta il codice di risposta in questo tentativo.
• Tentativi di riprovo pianificati. Poco tempo dopo il primo tentativo, viene pianificato un recapito successivo tramite la coda delle attività di WordPress. Se tale recapito restituisce una risposta 5xx o un errore di connessione, il plugin pianifica ulteriori riprovi con un breve ritardo crescente tra di essi.
• Limite massimo di riprovi. Il plugin non riprova all'infinito. Dopo un esiguo numero di tentativi non riusciti, l'evento viene scartato silenziosamente e non verrà recapitato in seguito.
• Indipendenza per singolo evento. Un errore di recapito per un evento non influisce sull'evento successivo.
• L'ordine non è garantito. Due eventi attivati a breve distanza l'uno dall'altro possono arrivare in qualsiasi ordine. I ricevitori dovrebbero fare affidamento sugli identificatori e sui timestamp nel payload, non sull'ordine di arrivo.
• Modello a ricevitore singolo. Ciascun evento ha esattamente un URL configurato. Per distribuire l'evento a più sistemi, configura un piccolo inoltratore (ad esempio una piattaforma di automazione come Zapier, Make, n8n o un relay ospitato in proprio) come ricevitore e lascia che sia questo a smistarlo ai sistemi a valle.
• Dipendenza da cron per i riprovi. I riprovi sono pianificati tramite la coda delle attività di WordPress. Sulle installazioni che utilizzano la modalità Server cron (vedi Server Cron Setup), assicurati che il job di supporto che chiama wp-cron.php sia attivo — altrimenti i riprovi pianificati non verranno eseguiti.

Note operative

• Registrazione dei log sul lato WordPress. Il plugin registra l'attività delle API e dell'importazione in wp-content/uploads/as24ci-logs/. Il recapito dei webhook fa parte del normale funzionamento e potrebbe non generare log dettagliati per impostazione predefinita. Il luogo più affidabile per vedere cosa è stato recapitato è il log del ricevitore stesso.
• Registrazione dei log sul lato ricevitore. Registra ogni richiesta ricevuta, inclusi gli header (con la firma) e il corpo grezzo, prima di qualsiasi elaborazione. Ciò rende molto più semplici sia la risposta agli incidenti che il debug. Applica le normali regole di protezione dei dati del ricevitore — i lead contengono dati personali.
• Dati personali. L'evento new_lead contiene dati personali inviati dal visitatore (come nome, indirizzo email, telefono, messaggio). Tratta il ricevitore come un responsabile del trattamento dei dati per queste informazioni e applica le tue normali regole sulla privacy. Vedi Lead Data and Consent e GDPR / DSGVO Notes.
• Rotazione del segreto. Quando modifichi il segreto del webhook nel plugin, aggiorna contemporaneamente il ricevitore. Fino a quando entrambe le parti non concordano, ogni recapito verrà rifiutato dal controllo della firma.
• Modifica dell'URL. L'aggiornamento dell'URL ha effetto a partire dall'evento successivo. Non esiste un meccanismo integrato per recapitare nuovamente gli eventi storici.
• Disabilitazione di un webhook. Cancella il campo dell'URL e salva. Non verranno più inviati eventi di quel tipo.

Limitazioni

• Vengono emessi solo i due eventi sopra descritti. Non esiste un evento integrato per l'eliminazione dei veicoli, la modifica dello stato dei lead, l'iscrizione agli avvisi di ricerca, la prenotazione di test drive o altre azioni del plugin.
• Non esiste un'interfaccia utente di amministrazione per ispezionare i singoli tentativi di recapito o per riprodurre eventi storici.
• Non esiste una distribuzione nativa (fan-out) a più ricevitori per evento.
• Non esiste un endpoint per webhook in entrata — il plugin invia solo webhook; non accetta webhook arbitrari in entrata.
• Il numero di riprovi e i relativi ritardi possono variare tra le versioni del plugin. Verifica il comportamento attuale rispetto a Webhook Event Reference prima di pubblicare documentazione rivolta ai clienti.

---

---

Risoluzione dei problemi

Documenti correlati

• Webhook Event Reference
• Webhooks (technical notes)
• Option Keys and Settings Storage
• Lead Data and Consent
• GDPR / DSGVO Notes
• Server Cron Setup
• External API Credentials
• Requisiti di API, rete e SSL
• Email and Lead Errors