Documentación · Guía de integración

Integración de Webhooks

Este documento explica cómo funcionan los webhooks salientes del plugin ADP Car Market Hub, cómo configurarlos de forma segura, cómo debe validar las cargas útiles (payloads) el sistema receptor y qué esperar a nivel operativo. También cubre las limitaciones de la implementación actual para que las integraciones puedan diseñarse teniendo estas en cuenta.

Cuándo usar este documento

Use este documento si está:

Conectando el plugin a un CRM, herramienta de enrutamiento de leads, servicio de notificaciones o plataforma de automatización de flujos de trabajo.
Construyendo u operando el endpoint receptor al que debe llamar el plugin.
Revisando la postura de seguridad de una integración de webhooks.
Solucionando problemas con un receptor que no parece ser llamado o que está rechazando las cargas útiles.

El público objetivo es un integrador o desarrollador que trabaja en el sistema receptor, junto con el administrador de WordPress que configura el plugin.

Descripción general

Un webhook es una solicitud HTTP saliente que el plugin envía a una URL de su elección cuando ocurre un evento específico en el sitio de WordPress. El plugin envía un documento JSON que describe el evento; el sistema receptor lo procesa como desee (crear un ticket en el CRM, publicar un mensaje de chat, añadirlo a una hoja de cálculo, enrutar un lead, etc.).

El plugin expone actualmente dos eventos:

new_lead — se activa cuando un visitante envía el formulario de contacto en la página de un vehículo y se guarda un lead.
new_import — se activa cuando el importador importa o actualiza un vehículo.

Nota sobre el comportamiento actual: En la versión actual del plugin, solo se envía realmente new_import. La ruta de new_lead está conectada (la URL de destino, el secreto y la firma funcionan), pero su activador no está activo en el código actual, por lo que una URL de new_lead configurada no recibirá solicitudes todavía. Mientras tanto, use los correos electrónicos de leads integrados para las notificaciones de leads, y configure new_lead ahora si desea que el receptor esté listo para cuando se active.

Cada evento tiene su propia URL de destino configurable. Se puede configurar un único secreto compartido para firmar cada carga útil con HMAC-SHA256, de modo que el receptor pueda verificar que la solicitud realmente provino del plugin.

Los webhooks son opcionales. Si no se configura una URL de destino, no se envía ninguna solicitud para ese evento.

Requisitos previos

Antes de configurar los webhooks, prepare:

Un endpoint receptor que acepte una solicitud HTTPS POST con un cuerpo JSON. Se recomienda encarecidamente HTTPS; un endpoint HTTP expone la carga útil en tránsito.
Conocimiento de cómo responde el receptor a los errores, para que el comportamiento de reintento descrito a continuación tenga sentido para su configuración.
Un valor de secreto compartido que pueda configurar tanto en el plugin como en el receptor (solo es necesario si desea la verificación de firma; muy recomendado).
Acceso de administrador de WordPress en el sitio que ejecuta el plugin.

Instrucciones paso a paso

Decida qué eventos reenviar. Puede configurar uno o ambos de new_lead y new_import. Deje una URL de destino vacía para desactivar ese evento.
Elija un secreto compartido. Use una cadena larga y aleatoria (por ejemplo, una contraseña generada por su gestor de contraseñas). Manténgala confidencial; nunca debe publicarse.
Abra los ajustes del plugin. Navegue a Car Market Hub → Leads. La sección Webhooks en la pestaña Leads contiene los campos New lead webhook URL, New import webhook URL y Webhook secret. Verifique la ubicación exacta en la versión actual del plugin, ya que la agrupación de la interfaz de usuario puede evolucionar entre versiones.
Configure las URLs. Pegue las URLs receptoras en los campos correspondientes. El plugin valida que el valor sea una URL sintácticamente correcta y omite el envío si falta o no es válida.
Configure el secreto. Pegue el secreto compartido en el campo Webhook secret. Configure el mismo valor en el receptor.
Guarde y active una prueba. Guarde los ajustes y luego provoque un evento real: - Para new_lead: envíe el formulario de lead en la página de detalles de un vehículo desde una ventana privada. - Para new_import: ejecute el importador (manualmente o espere a la siguiente ejecución programada) para que al menos un vehículo se inserte o actualice.
Confirme la recepción. Revise los logs del receptor para confirmar que la solicitud llegó y que la firma se verificó correctamente. Si algo va mal, consulte Solución de problemas a continuación.

Referencia de configuración

Ajuste	Propósito
New lead webhook URL	Endpoint al que se llama cuando el envío de un formulario de contacto se guarda como un lead.
New import webhook URL	Endpoint al que se llama cuando el importador importa o actualiza un vehículo.
Webhook secret	Secreto compartido utilizado para firmar cada carga útil con HMAC-SHA256. Cuando está vacío, no se envía cabecera de firma.

Las claves de opción correspondientes utilizadas internamente por el plugin están documentadas en Option Keys and Settings Storage y Webhook Event Reference.

Formato de la solicitud

El plugin envía cada evento como una solicitud HTTPS POST con un cuerpo JSON y las siguientes cabeceras:

Content-Type: application/json
X-AS24CI-Signature: <hex> — presente solo cuando se configura un secreto de webhook. El valor es el HMAC-SHA256 del cuerpo de la solicitud sin procesar, utilizando el secreto configurado como clave, codificado como una cadena hexadecimal en minúsculas.

El conjunto exacto de campos en el cuerpo JSON puede evolucionar entre las versiones del plugin. La referencia para la versión actual es Webhook Event Reference. Ambos eventos incluyen como mínimo:

event — el nombre del evento (new_lead o new_import).
timestamp — una marca de tiempo ISO-8601 en UTC de cuándo se preparó el evento.
Un identificador para el objeto WordPress relacionado (ID de lead para new_lead, ID de entrada y Listing ID para new_import).
Un objeto data con un pequeño conjunto de campos de resumen sobre el evento (campos básicos de lead para new_lead; campos básicos de vehículo para new_import).

Los receptores deben tratar los campos desconocidos como adiciones compatibles con versiones futuras e ignorarlos en lugar de rechazar la carga útil. Verifique el conjunto de campos actual con el documento de referencia antes de publicar su integración.

Validación de solicitudes entrantes

Cuando se configura un secreto de webhook, el receptor siempre debe verificar la firma antes de confiar en la carga útil. La regla de verificación es:

Lea el cuerpo de la solicitud sin procesar antes de cualquier análisis JSON (el análisis y la posterior reserialización pueden cambiar el orden de los bytes o los espacios en blanco y romper la firma).
Calcule HMAC-SHA256(raw_body, shared_secret) y codifique el resultado como una cadena hexadecimal en minúsculas.
Compárelo con el valor de la cabecera X-AS24CI-Signature utilizando una comparación de tiempo constante (la mayoría de los lenguajes proporcionan esto como hash_equals, crypto.timingSafeEqual, hmac.compare_digest o similar).
Rechace la solicitud con 401 si la firma falta o no coincide.

Comprobaciones defensivas adicionales que el receptor debería considerar:

Rechazar HTTP. Solo acepte solicitudes HTTPS en el receptor.
Permitir en lista blanca la IP de origen del sitio de WordPress en la capa de red o de aplicación, además de la comprobación de firma.
Idempotencia. El mismo evento lógico puede entregarse más de una vez (consulte Comportamiento de entrega a continuación). Use el ID de lead, el ID de entrada, el Listing ID o un hash de la carga útil para eliminar duplicados en el lado del receptor.
Ventana de marca de tiempo. Rechace solicitudes cuyo timestamp esté muy en el pasado o en el futuro para limitar la validez de las cargas útiles reproducidas. Es normal que haya unos minutos de desajuste de reloj en cualquier dirección.
Tolerancia de esquema. Trate los campos adicionales como compatibles con versiones futuras y los nombres de eventos desconocidos como algo que registrar en los logs en lugar de provocar un fallo.
Límite de tamaño del cuerpo. Limite el tamaño máximo del cuerpo en el receptor para protegerse contra entradas malformadas.

Si no se configura ningún secreto, el receptor no tiene forma de verificar que la solicitud realmente provino del plugin; configure un secreto a menos que la ruta de red sea completamente privada y de confianza.

Comportamiento de entrega

La implementación actual tiene las siguientes características de entrega. Verifique estos comportamientos en la versión actual del plugin antes de confiar en ellos.

El primer intento es de tipo disparar y olvidar (fire-and-forget). Cuando se activa un evento, el plugin envía la primera entrega como una solicitud HTTP POST no bloqueante. No espera la respuesta del receptor y no interpreta el código de respuesta en este intento.
Intentos de reintento programados. Poco tiempo después del primer intento, se programa una entrega de seguimiento a través de la cola de tareas de WordPress. Si esa entrega devuelve una respuesta 5xx o un error de conexión, el plugin programa nuevos reintentos con un breve retraso incremental entre ellos.
Límite de reintentos. El plugin no reintenta indefinidamente. Después de un pequeño número de intentos fallidos, el evento se descarta silenciosamente y no se entrega más tarde.
Independencia por evento. Un fallo de entrega para un evento no afecta al siguiente evento.
El orden no está garantizado. Dos eventos activados muy seguidos pueden llegar en cualquier orden. Los receptores deben confiar en los identificadores y las marcas de tiempo de la carga útil, no en el orden de llegada.
Modelo de receptor único. Cada evento tiene exactamente una URL configurada. Para distribuirlo a varios sistemas, configure un pequeño reenviador (por ejemplo, una plataforma de automatización como Zapier, Make, n8n o un relé autoalojado) como receptor y deje que este lo distribuya a los sistemas secundarios.
Dependencia de cron para los reintentos. Los reintentos se programan a través de la cola de tareas de WordPress. En instalaciones que utilizan el modo de cron del servidor (consulte Server Cron Setup), asegúrese de que la tarea complementaria que llama a wp-cron.php esté configurada; de lo contrario, los reintentos programados no se ejecutarán.

Notas operativas

Registro de logs en el lado de WordPress. El plugin registra la actividad de la API y de la importación en wp-content/uploads/as24ci-logs/. La entrega de webhooks es parte del funcionamiento normal y es posible que no genere logs detallados de forma predeterminada. El lugar más fiable para ver qué se entregó es el propio log del receptor.
Registro de logs en el lado del receptor. Registre cada solicitud recibida, incluidas las cabeceras (con la firma) y el cuerpo sin procesar, antes de cualquier procesamiento. Esto facilita enormemente tanto la respuesta a incidentes como la depuración. Aplique las reglas normales de protección de datos del receptor: los leads contienen datos personales.
Datos personales. El evento new_lead contiene datos personales enviados por el visitante (como nombre, dirección de correo electrónico, teléfono, mensaje). Trate al receptor como un encargado del tratamiento de datos para esta información y aplique sus reglas de privacidad habituales. Consulte Lead Data and Consent y GDPR / DSGVO Notes.
Rotación del secreto. Cuando cambie el secreto del webhook en el plugin, actualice el receptor al mismo tiempo. Hasta que ambos extremos coincidan, cada entrega será rechazada por la comprobación de firma.
Cambio de la URL. La actualización de la URL entra en vigor para el siguiente evento. No existe un mecanismo integrado para volver a entregar eventos históricos.
Desactivación de un webhook. Limpie el campo de la URL y guarde. No se enviarán más eventos de ese tipo.

Limitaciones

Solo se emiten los dos eventos descritos anteriormente. No hay ningún evento integrado para la eliminación de vehículos, el cambio de estado de un lead, la suscripción a alertas de búsqueda, la reserva de pruebas de conducción u otras acciones del plugin.
No hay una interfaz de usuario de administración para inspeccionar los intentos de entrega individuales o para reproducir eventos históricos.
No hay una distribución nativa (fan-out) a múltiples receptores por evento.
No hay un endpoint de webhook entrante: el plugin solo envía webhooks; no acepta webhooks entrantes arbitrarios.
El número de reintentos y los retrasos pueden cambiar entre las versiones del plugin. Verifique el comportamiento actual con Webhook Event Reference antes de publicar documentación de cara al cliente. ---

Resolución de problemas

Síntoma	Causa probable	Qué comprobar
El receptor nunca recibe una solicitud.	La URL del webhook está vacía, mal formada o es inaccesible desde el sitio WordPress (DNS, cortafuegos, HTTPS saliente bloqueado).	Vuelva a comprobar la URL en la pestaña Leads. Confirme que el HTTPS saliente funciona desde el host de WordPress (consulte Requisitos de API, red y SSL).
El receptor recibe la solicitud pero la firma no coincide.	El receptor está verificando el cuerpo analizado en lugar de los bytes sin procesar, el secreto difiere en ambos lados o la comparación no es de tiempo constante.	Verifique que el cuerpo sin procesar se lea antes del análisis JSON, que el secreto coincida exactamente (sin espacios en blanco ni saltos de línea) y que la comparación utilice una función de tiempo constante.
El receptor recibe la solicitud pero falta `X-AS24CI-Signature`.	El secreto del webhook está vacío en los ajustes del plugin.	Establezca un secreto, guarde y vuelva a probar.
Los envíos de formularios de contacto llegan al receptor pero el mismo lead se entrega varias veces.	Comportamiento esperado: el plugin intenta reintentos cuando una entrega anterior pareció fallida, y el primer intento es de tipo "disparar y olvidar".	Haga que el receptor sea idempotente utilizando `lead_id` (u otro identificador estable de la carga útil).
Los eventos `new_import` no llegan a pesar de que las importaciones se ejecutan.	La URL del webhook de nueva importación está vacía o mal configurada.	Vuelva a comprobar la URL en la pestaña Leads; verifique con una importación manual.
Los reintentos no parecen ocurrir.	WP-Cron está deshabilitado y no hay una tarea cron `wp-cron.php` complementaria configurada.	Consulte Server Cron Setup y añada la tarea complementaria.
El receptor devuelve `5xx` repetidamente durante incidentes.	Modo de fallo normal. El plugin lo reintentará un número pequeño de veces y luego desistirá para ese evento.	Haga que el receptor sea tolerante o use un búfer en el lado del receptor. No hay una repetición de administración integrada.
El valor del secreto del webhook aparece en un registro o captura de pantalla.	Redacción insuficiente.	Rote el secreto inmediatamente, actualice el plugin y el receptor, y vuelva a probar.