Riferimento degli eventi webhook

Questa appendice descrive gli eventi webhook in uscita attivati dal plugin ADP Car Market Hub.

Quando utilizzare questo documento

Utilizzare questo riferimento quando si compila un ricevitore, si verificano le firme o si documenta un'integrazione. Per la descrizione concettuale, vedere Webhooks.

Panoramica

Il plugin può attivare due eventi webhook in uscita:

• new_lead — quando l'invio di un modulo di contatto viene salvato come lead.
• new_import — quando un veicolo viene creato o aggiornato durante un'importazione.

Ciascun evento è un POST JSON inviato a un URL configurato dall'amministratore. Quando viene configurato un segreto condiviso, la richiesta trasporta anche un'intestazione di firma HMAC-SHA256 che il ricevitore può utilizzare per verificare il payload.

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

Nota sul comportamento attuale: Nella versione attuale del plugin viene effettivamente inviato solo new_import. Il percorso di consegna di new_lead è presente (il ricevitore, la firma e l'opzione as24ci_webhook_url_new_lead esistono tutti) ma il suo trigger non viene attivato nel codice attuale, quindi la configurazione di un URL new_lead non produrrà ancora richieste. Per le notifiche dei lead oggi, fare affidamento sulle e-mail dei lead (vedere Leads Reference). Lo schema seguente documenta il payload new_lead previsto per i ricevitori che desiderano essere pronti a gestirlo.

Riepilogo degli eventi

Un segreto di firma condiviso viene configurato a livello globale tramite as24ci_webhook_secret.

Formato del payload

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

new_lead

{
  "event": "new_lead",
  "timestamp": "2025-01-01T12:00:00+00:00",
  "lead_id": 0,
  "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": 0,
  "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 attuale del plugin. Verificare se la propria integrazione richiede di distinguere i due casi rispetto al codice sorgente attuale prima della pubblicazione.

Verifica della firma

Quando as24ci_webhook_secret è impostato, 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 ricevitore:

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

Se non è configurato alcun segreto, l'intestazione X-AS24CI-Signature non viene inviata. Le distribuzioni 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.
• In caso di errori di connessione o 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; correggere il ricevitore e riattivare l'evento di origine se necessario.
• I ricevitori dovrebbero rispondere entro 15 secondi e idealmente completare il lavoro pesante in modo asincrono.

Configurazione

Gli URL vengono convalidati con filter_var( ..., FILTER_VALIDATE_URL ). Gli URL non validi vengono saltati silenziosamente — impostare URL https:// validi in produzione.

Note operative

• Il plugin attiva solo 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 vostro caso d'uso, eseguite il ricevitore dietro un livello di accodamento.
• Ciascun webhook viene attivato dalla stessa richiesta WordPress che ha generato l'evento di origine. I ricevitori lenti non bloccheranno la richiesta rivolta all'utente perché il primo tentativo non è bloccante.
• Il payload new_lead include solo il piccolo set di campi mostrato sopra. Ulteriori metadati dei lead sono disponibili interrogando il post type as24ci_lead con le normali funzioni di WordPress.
• Il payload new_import rimane intenzionalmente ridotto. Per recuperare il record completo del veicolo, recuperare /wp-json/as24ci/v1/vehicles/<post_id> (quando l'API REST pubblica è abilitata).

Risoluzione dei problemi

• Il webhook non arriva mai. Verificare che l'URL sia HTTPS, raggiungibile dal server WordPress e che sia valido come URL. Controllare i log del plugin e il log degli errori del server web.
• Il webhook arriva una volta ma non ci sono tentativi successivi. Il primo tentativo è intenzionalmente fire-and-forget; verificare che l'evento as24ci_webhook_retry sia pianificato (si affida a WP-Cron o al vostro cron esterno).
• Mancata corrispondenza della firma sul ricevitore. Confermare che entrambe le parti utilizzino lo stesso identico segreto e che il ricevitore verifichi il corpo grezzo della richiesta senza riserializzarlo o formattarlo prima dell'hashing.
• 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.
• Tentativi bloccati. WP-Cron richiede un traffico regolare sul sito per attivarsi. Sui siti a basso traffico, configurare un vero processo cron o l'endpoint cron REST descritto in Riferimento agli hook cron.

Documenti correlati

• Webhooks
• Integrazione dei webhook
• Riferimento dell'endpoint REST
• Riferimento agli hook cron
• Riferimento delle impostazioni