> ## 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.

# Receive leads by webhook

> Choose and test Nexor's per-door webhook or generic Public API webhook for inbound leads.

Nexor has two inbound lead webhook contracts. They create leads through different configuration and authentication paths; do not combine their URLs or field-mapping formats.

## Choose the right endpoint

| Contract                   | URL                                                | Routing                            | Authentication                                     |
| -------------------------- | -------------------------------------------------- | ---------------------------------- | -------------------------------------------------- |
| Per-door webhook           | `https://api.getnexor.ai/hooks/:token`             | One agent saved on the door        | The unguessable token in the path                  |
| Generic Public API webhook | `https://api.getnexor.ai/api/public/leads/webhook` | `workflow_id` in the query or body | API key in `?token=`; `X-API-Key` is also accepted |

Use a per-door webhook when one external source always sends leads to the same agent and you want door-level activity, pause/resume, deduplication, and dry-run validation. Use the generic route for a headerless system that already has a Nexor API key, or when each request must select its agent.

<Warning>
  Both URLs contain or accept credentials. Never place a real URL or key in documentation, screenshots, analytics, or support messages. Rotate the credential if it is exposed.
</Warning>

## Per-door webhook

Create and manage this door from [Custom connection](/docs/en/guides/integrations/custom-connection). Its field map uses incoming paths as keys and Nexor fields as values:

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

Dot paths can traverse nested objects and numeric array positions. If `first_name` is mapped but `last_name` is not, Nexor splits a multi-word mapped name after the first word.

After mapping, the payload must contain at least one of `first_name`, `last_name`, `email`, or `phone`.

### Validate without creating a 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"}}'
```

A valid test returns `200`, `dry_run: true`, and the translated lead. It does not create a lead. Remove `dry_run=true` only after checking the translated identity and destination agent.

The endpoint allows 120 requests per IP address per minute. A disabled door returns `403`; an invalid token returns `404`; a payload without an identity field returns `400`. A new lead returns `201`. When door deduplication is enabled, Nexor checks email when present, otherwise phone, and an existing lead returns `200` with `duplicate: true`.

## Generic Public API webhook

The generic route uses the same single-lead processing as `POST /leads`. A `workflow_id` in the JSON body takes precedence over the query parameter.

```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"}'
```

If the sender supports headers, you can omit `?token=` and send `X-API-Key` instead. With no intake map on the key, the body must already use Nexor's canonical field names. With a per-key intake map, Nexor resolves configured aliases and can carry unconsumed fields into lead metadata.

`POST /api/public/leads/odoo` remains an identical compatibility alias. It is not the native Odoo API-key integration and should not be used as the name of a new custom connection.

<Note>
  These endpoints are headless and have no request screen to capture in staging. The Custom connection guide shows the real dashboard surface used to manage doors.
</Note>


## API Specification

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