Webhook

Questo documento descrive i webhook HTTP in uscita attivati dal plugin ADP Car Market Hub in modo che i sistemi esterni di CRM, notifica o automazione possano reagire agli eventi del plugin in tempo reale.

Quando utilizzare questo documento

Leggi questo documento se hai bisogno di:

• Collegare il plugin a un CRM esterno o a un servizio di notifica (ad esempio uno strumento di automazione dei flussi di lavoro) in modo che i nuovi lead o i veicoli appena importati attivino azioni in un altro sistema.
• Implementare un endpoint di ricezione che verifichi l'autenticità del webhook utilizzando la firma HMAC.
• Diagnosticare consegne di webhook mancate o duplicate.

Per l'HTTP in entrata, consulta REST API Endpoints.

Panoramica

Il plugin può attivare due eventi webhook in uscita:

• new_lead — destinato ad attivarsi quando l'invio di un modulo di contatto viene salvato come post di tipo lead. AS24CI\Webhooks è in ascolto sull'azione as24ci_lead_saved, ma nella versione corrente del plugin tale azione non viene inviata in alcun punto del codice (il lead viene salvato tramite Leads_CPT::save_lead() senza attivare l'hook), pertanto il webhook new_lead attualmente non si attiva. Considera questo evento come dormiente fino a quando il punto di attivazione non verrà ripristinato.
• new_import — attivato quando un veicolo viene creato o aggiornato durante un'importazione (tramite l'azione as24ci_vehicle_imported). Questo evento è attivo.

Ciascun evento invia una richiesta POST con payload JSON a un URL configurato dall'amministratore. Quando viene configurato un segreto condiviso, ogni richiesta contiene anche un'intestazione con firma HMAC-SHA256 che il ricevente può utilizzare per verificare il payload.

I webhook sono indipendenti: la configurazione di uno non abilita l'altro. Lasciare un URL vuoto disabilita completamente quell'evento.

Requisiti o prerequisiti

• Un endpoint HTTPS raggiungibile sul lato ricevente.
• (Opzionale ma fortemente raccomandato) un segreto condiviso memorizzato nelle impostazioni del plugin e sul ricevente, utilizzato per verificare la firma.
• Per l'evento new_lead: nota l'avvertenza sopra riportata — l'azione as24ci_lead_saved non è attualmente inviata, quindi questo evento non si attiverà nella versione corrente del plugin anche con un URL configurato.
• Per l'evento new_import: il motore di importazione deve essere configurato e funzionante. Consulta Import Engine.

Istruzioni passo dopo passo

1. Apri l'amministrazione del plugin e individua i campi del webhook. Sono esposti nella scheda Leads come campi di input denominati New lead webhook URL, New import webhook URL e Webhook secret.
2. Inserisci un URL https:// valido per ogni evento che desideri ricevere.
3. Genera un segreto casuale sicuro (ad esempio una stringa di oltre 32 caratteri) e incollalo nel campo Webhook secret. Configura lo stesso valore sul ricevente.
4. Salva le impostazioni. Il plugin memorizza i valori nelle opzioni as24ci_webhook_url_new_lead, as24ci_webhook_url_new_import e as24ci_webhook_secret.
5. Attiva un evento di test: - Per new_lead: invia un modulo di contatto di prova sul frontend. - Per new_import: esegui un'importazione che crei o aggiorni almeno un veicolo.
6. Conferma la ricezione e la verifica della firma sul lato ricevente.

Riferimento del payload

Tutti i payload sono oggetti JSON con event, timestamp (ISO 8601, UTC) e un blocco di dati specifico per event.

new_lead

{
  "event": "new_lead",
  "timestamp": "2025-01-01T12:00:00+00:00",
  "lead_id": 123,
  "data": {
    "name": "",
    "email": "",
    "phone": "",
    "message": "",
    "vehicle_id": 0,
    "vehicle_title": "",
    "vehicle_url": ""
  }
}

new_import

{
  "event": "new_import",
  "timestamp": "2025-01-01T12:00:00+00:00",
  "post_id": 456,
  "listing_id": "",
  "data": {
    "title": "",
    "url": "",
    "make": "",
    "model": "",
    "price": 0
  }
}

Il payload new_import viene attivato sia per i nuovi inserimenti che per gli aggiornamenti. Il callback dell'hook riceve internamente un flag is_update; il payload in uscita stesso non include questo flag nella versione corrente del plugin. Verifica se la tua integrazione richiede la distinzione dei due casi e conferma il comportamento corrente rispetto al codice sorgente prima di pubblicare testi destinati ai clienti.

Autenticazione e verifica della firma

Quando l'opzione as24ci_webhook_secret è impostata, il plugin aggiunge l'intestazione:

X-AS24CI-Signature: <hmac_sha256(payload_json, secret)>

La firma viene calcolata sull'esatto corpo JSON inviato nella richiesta. Per verificare sul ricevente:

1. Leggi il corpo grezzo della richiesta senza ricodificarlo.
2. Calcola hash_hmac('sha256', body, secret) utilizzando lo stesso segreto condiviso.
3. Confrontalo con X-AS24CI-Signature utilizzando un confronto a tempo costante (ad es. hash_equals in PHP).

Se non è configurato alcun segreto, l'intestazione X-AS24CI-Signature non viene inviata. Le installazioni in produzione dovrebbero sempre configurare un segreto.

Consegna, tentativi e timeout

• Le richieste utilizzano wp_remote_post() con un timeout di 15 secondi.
• Il primo tentativo non è bloccante (fire and forget). Il plugin pianifica quindi un evento cron di follow-up (as24ci_webhook_retry) circa 60 secondi dopo che esegue un rinvio bloccante in modo da poter ispezionare il codice di risposta.
• Se la risposta è un errore di connessione o un HTTP 5xx, il plugin pianifica ulteriori tentativi con un backoff di tipo esponenziale (~2 minuti, poi ~4 minuti), fino a un massimo di tre tentativi in totale.
• Le risposte HTTP 4xx sono trattate come definitive e non vengono riprovate; correggi il ricevente e riattiva l'evento di origine se necessario.
• I riceventi dovrebbero rispondere entro 15 secondi e idealmente completare qualsiasi lavoro pesante in modo asincrono.

Riferimento di configurazione

Per l'elenco completo delle opzioni del plugin, consulta Options And Settings Storage.

Note operative

• Gli URL vengono validati con filter_var( ..., FILTER_VALIDATE_URL ). Gli URL non validi vengono saltati silenziosamente — imposta URL https:// validi in produzione.
• Il plugin si limita ad attivare i webhook; non mantiene una coda di consegna, un registro di riproduzione o un archivio dei messaggi non recapitati. Se una consegna affidabile e ordinata è fondamentale per il tuo caso d'uso, gestisci il ricevente attraverso un livello di accodamento (ad esempio una funzione serverless con una coda di tentativi integrata).
• Ciascun webhook viene attivato dalla stessa richiesta WordPress che ha generato l'evento di origine. I riceventi lenti non bloccheranno la richiesta lato utente perché il primo tentativo non è bloccante.
• Il payload new_lead include solo il piccolo set di campi mostrato sopra. Ulteriori metadati del lead sono disponibili tramite la WP REST API o interrogando il tipo di post as24ci_lead con le normali funzioni WordPress.
• Il payload new_import rimane intenzionalmente di dimensioni ridotte. Per recuperare il record completo del veicolo, richiama /wp-json/as24ci/v1/vehicles/<post_id> (quando la REST API pubblica è abilitata).

Risoluzione dei problemi

• Il webhook non arriva mai — verifica che l'URL sia HTTPS, raggiungibile dal server WordPress e che sia valido come URL. Controlla i log del plugin e il log degli errori del tuo server web.
• Il webhook arriva una volta ma non ci sono tentativi — il primo tentativo è intenzionalmente di tipo "invia e dimentica"; verifica che l'evento as24ci_webhook_retry sia pianificato (si affida a WP-Cron o al tuo cron esterno).
• Mancata corrispondenza della firma sul ricevente — conferma che entrambe le parti utilizzino lo stesso identico segreto e che il ricevente verifichi il corpo grezzo della richiesta senza serializzarlo nuovamente o formattarlo prima di calcolare l'hash.
• Consegne duplicate di new_import — il rilevamento delle modifiche salta i veicoli il cui payload è invariato, ma una sincronizzazione completa forzata potrebbe emettere nuovamente eventi per annunci già noti. Consulta Import Engine per le regole di rilevamento delle modifiche.
• Tentativi bloccati — WP-Cron richiede traffico regolare sul sito per attivarsi. Sui siti a basso traffico, configura un vero processo cron o l'endpoint cron REST descritto in Cron Events And Scheduler.

Documenti correlati

• REST API Endpoints
• Cron Events And Scheduler
• Lead Storage And Processing
• Import Engine
• Options And Settings Storage
• Security And Capabilities