Webhooks

Este documento describe los webhooks HTTP salientes activados por el plugin ADP Car Market Hub para que los sistemas externos de CRM, notificación o automatización puedan reaccionar a los eventos del plugin en tiempo real.

Cuándo utilizar este documento

Lea este documento si necesita:

• Conectar el plugin a un CRM externo o a un servicio de notificación (por ejemplo, una herramienta de automatización de flujos de trabajo) para que los nuevos leads o los vehículos recién importados activen acciones en otro sistema.
• Implementar un endpoint receptor que verifique la autenticidad del webhook utilizando la firma HMAC.
• Diagnosticar entregas de webhooks fallidas o duplicadas.

Para HTTP entrante, consulte REST API Endpoints.

Descripción general

El plugin puede activar dos eventos de webhook salientes:

• new_lead: diseñado para activarse cuando el envío de un formulario de contacto se guarda como una entrada de lead. AS24CI\Webhooks escucha en la acción as24ci_lead_saved, pero en la versión actual del plugin esa acción no se envía a ninguna parte del código (el lead se guarda a través de Leads_CPT::save_lead() sin activar el hook), por lo que el webhook new_lead no se activa actualmente. Considere este evento como inactivo hasta que se restablezca el punto de activación.
• new_import: se activa cuando se crea o actualiza un vehículo durante una importación (a través de la acción as24ci_vehicle_imported). Este evento está activo.

Cada evento envía una solicitud POST con un payload JSON a una URL configurada por el administrador. Cuando se configura un secreto compartido, cada solicitud también lleva una cabecera de firma HMAC-SHA256 que el receptor puede utilizar para verificar el payload.

Los webhooks son independientes: configurar uno no habilita el otro. Dejar una URL vacía desactiva ese evento por completo.

Requisitos o prerrequisitos

• Un endpoint HTTPS accesible en el lado del receptor.
• (Opcional pero muy recomendado) un secreto compartido almacenado en los ajustes del plugin y en el receptor, utilizado para verificar la firma.
• Para el evento new_lead: tenga en cuenta la advertencia anterior (la acción as24ci_lead_saved no se envía actualmente, por lo que este evento no se activará en la versión actual del plugin, incluso con una URL configurada).
• Para el evento new_import: el motor de importación debe estar configurado y en funcionamiento. Consulte Import Engine.

Instrucciones paso a paso

1. Abra la administración del plugin y localice los campos de webhook. Se encuentran en la pestaña Leads como los campos de entrada etiquetados como New lead webhook URL, New import webhook URL y Webhook secret.
2. Introduzca una URL https:// válida para cada evento que desee recibir.
3. Genere un secreto aleatorio seguro (por ejemplo, una cadena de más de 32 caracteres) y péguelo en el campo Webhook secret. Configure el mismo valor en el receptor.
4. Guarde los ajustes. El plugin almacena los valores en las opciones as24ci_webhook_url_new_lead, as24ci_webhook_url_new_import y as24ci_webhook_secret.
5. Active un evento de prueba: - Para new_lead: envíe un formulario de contacto de prueba en el frontend. - Para new_import: ejecute una importación que cree o actualice al menos un vehículo.
6. Confirme la recepción y la verificación de la firma en el lado del receptor.

Referencia de payload

Todos los payloads son objetos JSON con event, timestamp (ISO 8601, UTC) y un bloque de datos específico de 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
  }
}

El payload de new_import se activa tanto para nuevas inserciones como para actualizaciones. La llamada de retorno (callback) del hook recibe internamente un flag is_update; el propio payload saliente no incluye este flag en la versión actual del plugin. Verifique si su integración requiere distinguir ambos casos y confirme el comportamiento actual con el código fuente antes de publicar textos dirigidos al cliente.

Autenticación y verificación de firmas

Cuando se establece la opción 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 bruto de la solicitud sin volver a codificarlo.
2. Calcule hash_hmac('sha256', body, secret) utilizando el mismo secreto compartido.
3. Compárelo con X-AS24CI-Signature utilizando una comparación de tiempo constante (por ejemplo, hash_equals en PHP).

Si no se configura ningún secreto, 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 (fire and forget). A continuación, el plugin programa un evento 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.
• Si la respuesta es un error de conexión o un HTTP 5xx, el plugin programa reintentos adicionales con un retraso de estilo exponencial (~2 minutos, luego ~4 minutos), hasta un máximo de tres intentos en total.
• Las respuestas HTTP 4xx se tratan como definitivas 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 cualquier trabajo pesado de forma asíncrona.

Referencia de configuración

Para obtener la lista completa de opciones del plugin, consulte Options And Settings Storage.

Notas operativas

• 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.
• El plugin solo activa 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 a través de una capa de cola (por ejemplo, una función serverless con una cola de reintentos integrada).
• Cada webhook se activa desde la misma solicitud WordPress que generó el evento de origen. Los receptores lentos no ralentizarán la solicitud del usuario porque el primer intento no es bloqueante.
• El payload de new_lead solo incluye el pequeño conjunto de campos que se muestra arriba. Los metadatos adicionales del lead están disponibles a través de la WP REST API o consultando el tipo de contenido personalizado as24ci_lead con las funciones normales de WordPress.
• El payload de new_import se mantiene pequeño de forma intencionada. Para recuperar el registro completo del vehículo, obtenga /wp-json/as24ci/v1/vehicles/<post_id> (cuando la REST API 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. Revise los registros del plugin y el registro de errores de su 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 utilizan exactamente el mismo secreto y que el receptor verifica el cuerpo bruto de la solicitud sin volver a serializarlo ni formatearlo antes de realizar el hash.
• Entregas duplicadas de new_import: la detección de cambios omite los vehículos cuyo payload no ha cambiado, pero una sincronización completa forzada puede volver a emitir eventos para anuncios ya conocidos. Consulte Import Engine para conocer las reglas de detección de cambios.
• Reintentos atascados: WP-Cron requiere tráfico regular en el sitio para activarse. En sitios con poco tráfico, configure una tarea cron real o el endpoint cron REST descrito en Cron Events And Scheduler.

Documentos relacionados

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