Skip to main content
El Custom Webhook recibe un lead enviado a DeltaLead desde un sistema externo. Una sola ruta, un solo propósito, una sola cabecera obligatoria. Para crear claves desde el panel y entender la diferencia entre modos, ver la guía del Custom Webhook.

​
Endpoint

​
Autenticación

La clave se envía como bearer token:
El esquema se compara sin distinguir mayúsculas y el token se recorta, de modo que bearer dl_live_abc también se acepta. La clave identifica tanto la cuenta como el modo: ningún otro dato de la solicitud los determina.
Una cabecera ausente, una cabecera mal formada, una clave desconocida, una clave revocada y una clave vencida devuelven la misma respuesta 401 unauthorized. Los cuerpos son idénticos a propósito: el error no permite deducir si una clave existe.

​
Cuerpo de la solicitud

El cuerpo es un objeto JSON con una única clave lead. El contrato de lead v1 exige lead.name y al menos uno de lead.email o lead.phone. Si falta cualquiera de las dos condiciones, la respuesta es 400 missing_required_fields.
​
string
requerido
Nombre completo del lead. DeltaLead lo divide en el primer espacio: todo lo anterior pasa a ser el nombre y todo lo posterior, el apellido. "María García" produce María / García, y "Probe Alpha Betamax" produce Probe / Alpha Betamax.La división es posicional, no lingüística, así que un nombre compuesto termina en el campo de apellido: "María José García" produce María / José García. Si el sistema de origen ya guarda nombre y apellido por separado, conviene unirlos con un solo espacio en ese orden en lugar de enviar un nombre para mostrar.
​
string
Dirección de correo. Obligatoria salvo que se envíe lead.phone.
​
string
Número de teléfono. Obligatorio salvo que se envíe lead.email. Se recomienda el formato E.164, por ejemplo +5491155551234.
​
string
Etiqueta libre que indica el origen del envío, por ejemplo landing-page. Queda registrada en el lead y la usa el procesamiento posterior: aparece en el Resumen de IA del lead. Todo envío por este endpoint se reporta en el lead con el canal Custom, sin importar qué se envíe aquí, así que source sirve para distinguir cuál de los sistemas propios generó el lead.
​
string
Descripción libre del vehículo por el que consulta el lead, por ejemplo Toyota Hilux SRX 2024. Queda registrada en el lead y la usa el Resumen de IA para buscar coincidencias en el stock del catálogo, así que conviene enviar lo que escribió el comprador y no un código interno de stock.
​
string
Contexto libre del lado del integrador. Se agrega a las Notas del lead, atribuido al webhook y visible para el asesor. Se deduplica por envío, de modo que un reintento no agrega la misma nota dos veces.
​
object
Objeto JSON arbitrario que se guarda en el lead como passthrough y se combina entre envíos en lugar de sobrescribirse. Sirve para identificadores del sistema de origen que no tienen lugar en el contrato. DeltaLead no lo interpreta y nunca se le muestra al agente de IA. Las claves que contienen . o $ se rechazan.
Estos siete campos son todo el contrato. Cualquier otra clave dentro de lead se acepta —la solicitud igual devuelve 200— pero se descarta y nunca llega al registro del lead. Todo lo que quede fuera del contrato va en metadata, el único campo que acepta una forma arbitraria.

​
Idempotencia

La cabecera opcional Idempotency-Key vuelve seguros los reintentos:
Un envío que trae una clave ya vista para la cuenta devuelve 200 {"status": "duplicate"} y no crea nada. Las claves de idempotencia tienen alcance de cuenta, no de modo. Un valor ya usado con una clave sandbox suprime ese mismo valor cuando después llega con una clave live, así que no conviene arrastrar los valores de prueba al cambiar de modo.
Sin Idempotency-Key, el endpoint no detecta repeticiones. Todo envío se acepta y devuelve {"status": "ok"}, incluso uno idéntico byte a byte al anterior. Conviene mandar la cabecera en cualquier solicitud que el cliente pueda reintentar: es la única forma de que una repetición se informe en lugar de aceptarse en silencio.
La clave debe derivarse de algo estable del sistema de origen, como el ID de envío del formulario que generó el lead. Reutilizar ese valor en cada reintento del mismo envío es lo que vuelve seguro el reintento.

​
Coincidencia de contactos

Hay dos mecanismos de deduplicación, en capas distintas, y conviene no confundirlos. Idempotency-Key deduplica envíos. Una repetición se rechaza antes de hacer cualquier trabajo y se informa como {"status": "duplicate"}. La coincidencia de contactos deduplica personas. Una vez aceptado el envío, DeltaLead lo compara con los contactos existentes por correo o teléfono. Una coincidencia se resuelve sobre el lead existente y lo enriquece en lugar de crear un segundo: un envío que solo trae teléfono puede sumarse a un lead creado antes a partir de un correo, y el contacto termina con ambos datos. La consecuencia práctica es que un envío que coincide con un contacto existente igual devuelve {"status": "ok"}, no duplicate. El 200 indica que el envío fue aceptado; nunca indica si se creó un lead nuevo.
La coincidencia es por correo o teléfono, no por ambos. Dos personas realmente distintas que comparten un teléfono —un hogar, o la central de un concesionario— se resuelven sobre el mismo lead. Conviene enviar los datos de contacto más específicos disponibles.

​
Límites

Los límites de tasa se aplican por ruta.

​
Respuestas

Un envío exitoso devuelve un status:
200 OK
Un fallo devuelve un sobre de error, donde detail identifica la causa:
401 Unauthorized
La ruta acepta únicamente POST. Cualquier otro método, o cualquier otra ruta en este host, devuelve 404 {"message": "Not Found"} desde el gateway, antes de que corra el handler del webhook. Un 200 confirma que DeltaLead aceptó el envío, no que el lead exista. El lead se crea de forma asíncrona unos segundos después.
Un 500 enqueue_failed se puede reintentar: el envío era válido y el fallo es del lado de DeltaLead. Ningún 4xx debe reintentarse, porque la solicitud volverá a fallar igual. Conviene mandar siempre una Idempotency-Key en solicitudes que puedan reintentarse, ya que los reintentos solo se deduplican con esa cabecera.

​
Ejemplos

Sandbox, la solicitud válida mínima:
cURL
Live, la misma solicitud con todos los campos:
cURL
Live, con clave de idempotencia, seguro de reintentar:
cURL