Referencia de eventos de webhook

Este apéndice describe los eventos de webhook salientes emitidos por el plugin ADP Car Market Hub.

Cuándo utilizar este documento

Utilice esta referencia cuando cree un receptor, cuando verifique firmas o cuando documente una integración. Para la descripción conceptual, consulte Webhooks.

Descripción general

El plugin puede emitir dos eventos de webhook salientes:

• new_lead: cuando el envío de un formulario de contacto se guarda como un lead.
• new_import: cuando se crea o actualiza un vehículo durante una importación.

Cada evento es un POST JSON a una URL configurada por el administrador. Cuando se configura un secreto compartido, la solicitud también lleva una cabecera de firma HMAC-SHA256 que el receptor puede utilizar para verificar la carga útil (payload).

Los eventos son independientes: configurar una URL no habilita la otra. Dejar una URL vacía desactiva ese evento por completo.

Nota sobre el comportamiento actual: En la versión actual del plugin, solo se envía realmente new_import. La ruta de entrega de new_lead está presente (el receptor, la firma y la opción as24ci_webhook_url_new_lead existen), pero su activador no se ejecuta en el código actual, por lo que configurar una URL de new_lead aún no producirá solicitudes. Para las notificaciones de leads hoy en día, confíe en los correos electrónicos de leads (consulte Referencia de Leads). El esquema a continuación documenta la carga útil de new_lead prevista para los receptores que deseen estar preparados para ella.

Resumen de eventos

Se configura un secreto de firma compartido de forma global a través de as24ci_webhook_secret.

Formato de la carga útil

Todas las cargas útiles son objetos JSON con event, timestamp (ISO 8601, UTC) y un bloque de datos específico del 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
  }
}

La carga útil de new_import se emite tanto para nuevas inserciones como para actualizaciones. La devolución de llamada (callback) del hook recibe internamente un indicador is_update; la propia carga útil saliente no incluye este indicador en la versión actual del plugin. Verifique si su integración requiere distinguir los dos casos frente al código fuente actual antes de publicar.

Verificación de firma

Cuando se establece as24ci_webhook_secret, el plugin añade la cabecera:

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

La firma se calcula sobre el cuerpo JSON exacto enviado en la solicitud. Para verificar en el receptor:

1. Lea el cuerpo de la solicitud sin procesar sin volver a codificarlo.
2. Calcule hash_hmac('sha256', body, secret) utilizando el mismo secreto compartido.
3. Compare el resultado con X-AS24CI-Signature utilizando una comparación de tiempo constante (por ejemplo, hash_equals en PHP).

Si no hay ningún secreto configurado, no se envía la cabecera X-AS24CI-Signature. Los despliegues en producción siempre deben configurar un secreto.

Entrega, reintentos y tiempos de espera

• Las solicitudes utilizan wp_remote_post() con un tiempo de espera de 15 segundos.
• El primer intento no es bloqueante ("disparar y olvidar"). A continuación, el plugin programa un evento de cron de seguimiento (as24ci_webhook_retry) unos 60 segundos más tarde que realiza un reenvío bloqueante para que se pueda inspeccionar el código de respuesta.
• En caso de errores de conexión o HTTP 5xx, el plugin programa reintentos adicionales con un retroceso de estilo exponencial (~2 minutos, luego ~4 minutos), hasta un máximo de tres intentos en total.
• Las respuestas HTTP 4xx se tratan como terminales y no se reintentan; corrija el receptor y vuelva a activar el evento de origen si es necesario.
• Los receptores deben responder en un plazo de 15 segundos e, idealmente, completar el trabajo pesado de forma asíncrona.

Configuración

Las URL se validan con filter_var( ..., FILTER_VALIDATE_URL ). Las URL no válidas se omiten silenciosamente; configure URL https:// válidas en producción.

Notas operativas

• El plugin solo emite webhooks; no mantiene una cola de entrega, un registro de reproducción ni un almacén de mensajes no entregados. Si la entrega fiable y ordenada es fundamental para su caso de uso, ejecute el receptor detrás de una capa de cola.
• Cada webhook se emite desde la misma solicitud de WordPress que generó el evento de origen. Los receptores lentos no detendrán la solicitud orientada al usuario porque el primer intento no es bloqueante.
• La carga útil de new_lead solo incluye el pequeño conjunto de campos que se muestran arriba. Los metadatos adicionales del lead están disponibles consultando el tipo de contenido personalizado as24ci_lead con las funciones normales de WordPress.
• La carga útil de new_import se mantiene pequeña de forma intencionada. Para recuperar el registro completo del vehículo, obtenga /wp-json/as24ci/v1/vehicles/<post_id> (cuando la API REST pública esté habilitada).

Resolución de problemas

• El webhook nunca llega. Verifique que la URL sea HTTPS, accesible desde el servidor de WordPress y que se valide como una URL. Compruebe los registros del plugin y el registro de errores del servidor web.
• El webhook llega una vez pero no hay reintentos. El primer intento es intencionadamente de tipo "disparar y olvidar"; verifique que el evento as24ci_webhook_retry se esté programando (depende de WP-Cron o de su cron externo).
• Discrepancia de firma en el receptor. Confirme que ambas partes utilicen exactamente el mismo secreto y que el receptor verifique el cuerpo de la solicitud sin procesar sin volver a serializarlo ni formatearlo antes de realizar el hash.
• Entregas de new_import duplicadas. La detección de cambios omite los vehículos cuya carga útil no ha cambiado, pero una sincronización completa forzada puede volver a emitir eventos para anuncios que ya se conocen.
• Reintentos atascados. WP-Cron requiere tráfico regular en el sitio para ejecutarse. En sitios con poco tráfico, configure una tarea de cron real o el endpoint de cron REST descrito en la Referencia de hooks de cron.

Documentos relacionados

• Webhooks
• Integración de Webhooks
• Referencia de endpoints REST
• Referencia de hooks de cron
• Referencia de ajustes