> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnexor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Recibir leads por webhook

> Elige y prueba el webhook por puerta o el webhook genérico de la API pública para recibir leads.

Nexor tiene dos contratos de webhook para recibir leads. Crean leads mediante configuraciones y autenticaciones distintas; no mezcles sus URLs ni sus formatos de mapeo.

## Elige el endpoint correcto

| Contrato                           | URL                                                | Enrutamiento                     | Autenticación                                      |
| ---------------------------------- | -------------------------------------------------- | -------------------------------- | -------------------------------------------------- |
| Webhook por puerta                 | `https://api.getnexor.ai/hooks/:token`             | Un agente guardado en la puerta  | Token difícil de adivinar en el path               |
| Webhook genérico de la API pública | `https://api.getnexor.ai/api/public/leads/webhook` | `workflow_id` en el query o body | Clave API en `?token=`; también acepta `X-API-Key` |

Usa un webhook por puerta cuando una fuente externa siempre envíe leads al mismo agente y necesites actividad por puerta, pausa, deduplicación y validación sin crear registros. Usa la ruta genérica para un sistema sin headers que ya tenga una clave API de Nexor, o cuando cada solicitud deba elegir su agente.

<Warning>
  Ambas URLs contienen o aceptan credenciales. Nunca pongas una URL o clave real en documentación, capturas, analítica o mensajes de soporte. Rota la credencial si queda expuesta.
</Warning>

## Webhook por puerta

Crea y administra esta puerta desde [Conexión personalizada](/docs/es/guides/integrations/custom-connection). Su mapa usa rutas de entrada como claves y campos de Nexor como valores:

```json theme={null}
{
  "contact.email": "email",
  "contact.phone": "phone",
  "contact.name": "first_name"
}
```

Las rutas con puntos pueden recorrer objetos anidados y posiciones numéricas de arreglos. Si mapeas `first_name` pero no `last_name`, Nexor divide un nombre compuesto después de la primera palabra.

Después del mapeo, el payload debe contener al menos uno de estos campos: `first_name`, `last_name`, `email` o `phone`.

### Valida sin crear un lead

```bash theme={null}
curl -X POST \
  'https://api.getnexor.ai/hooks/YOUR_WEBHOOK_TOKEN?dry_run=true' \
  -H 'Content-Type: application/json' \
  -d '{"contact":{"name":"Ada Lovelace","email":"ada@example.com"}}'
```

Una prueba válida devuelve `200`, `dry_run: true` y el lead traducido. No crea un lead. Quita `dry_run=true` solo después de revisar la identidad traducida y el agente de destino.

El endpoint permite 120 solicitudes por dirección IP por minuto. Una puerta deshabilitada devuelve `403`; un token inválido devuelve `404`; un payload sin campo de identidad devuelve `400`. Un lead nuevo devuelve `201`. Si la deduplicación está habilitada, Nexor revisa el email cuando existe y, en caso contrario, el teléfono. Un lead existente devuelve `200` con `duplicate: true`.

## Webhook genérico de la API pública

La ruta genérica usa el mismo procesamiento de un lead que `POST /leads`. Un `workflow_id` dentro del body JSON tiene prioridad sobre el parámetro del query.

```bash theme={null}
curl -X POST \
  'https://api.getnexor.ai/api/public/leads/webhook?token=YOUR_API_KEY&workflow_id=00000000-0000-4000-8000-000000000000' \
  -H 'Content-Type: application/json' \
  -d '{"first_name":"Ada","email":"ada@example.com","source":"website"}'
```

Si el sistema permite headers, puedes omitir `?token=` y enviar `X-API-Key`. Sin un mapa de entrada en la clave, el body debe usar los nombres de campo de Nexor. Con un mapa por clave, Nexor resuelve los alias configurados y puede guardar en metadata los campos que no fueron consumidos.

`POST /api/public/leads/odoo` se conserva como un alias de compatibilidad idéntico. No es la integración nativa de Odoo por clave API y no debe usarse como nombre para una conexión personalizada nueva.

<Note>
  Estos endpoints no tienen una pantalla propia para capturar en staging. La guía de Conexión personalizada muestra la superficie real del dashboard donde se administran las puertas.
</Note>


## API Specification

The full API specification for this endpoint is available in the [documentation index](https://docs.getnexor.ai/llms.txt).