Receive leads by webhook

Receive an inbound lead by webhook

curl --request POST \
  --url 'https://api.getnexor.ai/api/public/leads/webhook?token=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "first_name": "Maria",
  "last_name": "Soto",
  "email": "maria@example.com",
  "external_id": "crm-1842"
}
'

import requests

url = "https://api.getnexor.ai/api/public/leads/webhook?token="

payload = {
    "first_name": "Maria",
    "last_name": "Soto",
    "email": "maria@example.com",
    "external_id": "crm-1842"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    first_name: 'Maria',
    last_name: 'Soto',
    email: 'maria@example.com',
    external_id: 'crm-1842'
  })
};

fetch('https://api.getnexor.ai/api/public/leads/webhook?token=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getnexor.ai/api/public/leads/webhook?token=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'first_name' => 'Maria',
    'last_name' => 'Soto',
    'email' => 'maria@example.com',
    'external_id' => 'crm-1842'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getnexor.ai/api/public/leads/webhook?token="

	payload := strings.NewReader("{\n  \"first_name\": \"Maria\",\n  \"last_name\": \"Soto\",\n  \"email\": \"maria@example.com\",\n  \"external_id\": \"crm-1842\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getnexor.ai/api/public/leads/webhook?token=")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"Maria\",\n  \"last_name\": \"Soto\",\n  \"email\": \"maria@example.com\",\n  \"external_id\": \"crm-1842\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getnexor.ai/api/public/leads/webhook?token=")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"Maria\",\n  \"last_name\": \"Soto\",\n  \"email\": \"maria@example.com\",\n  \"external_id\": \"crm-1842\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "lead": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "source": "<string>",
    "metadata": {},
    "created_at": "2023-11-07T05:31:56Z",
    "last_name": "<string>",
    "email": "jsmith@example.com",
    "phone": "<string>",
    "company": "<string>",
    "title": "<string>",
    "campaign_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_to": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_user": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    }
  },
  "workflow_run": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "job_id": "<string>",
    "workflow": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    },
    "cadence": {
      "stepIndex": 123,
      "channel": "<string>",
      "attemptNumber": 123,
      "maxAttempts": 123,
      "totalSteps": 123
    }
  },
  "warning": "<string>"
}

{
  "success": true,
  "lead": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "source": "<string>",
    "metadata": {},
    "created_at": "2023-11-07T05:31:56Z",
    "last_name": "<string>",
    "email": "jsmith@example.com",
    "phone": "<string>",
    "company": "<string>",
    "title": "<string>",
    "campaign_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_to": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_user": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    }
  },
  "workflow_run": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "job_id": "<string>",
    "workflow": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    },
    "cadence": {
      "stepIndex": 123,
      "channel": "<string>",
      "attemptNumber": 123,
      "maxAttempts": 123,
      "totalSteps": 123
    }
  },
  "warning": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

POST

leads

webhook

Receive an inbound lead by webhook

curl --request POST \
  --url 'https://api.getnexor.ai/api/public/leads/webhook?token=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "first_name": "Maria",
  "last_name": "Soto",
  "email": "maria@example.com",
  "external_id": "crm-1842"
}
'

import requests

url = "https://api.getnexor.ai/api/public/leads/webhook?token="

payload = {
    "first_name": "Maria",
    "last_name": "Soto",
    "email": "maria@example.com",
    "external_id": "crm-1842"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    first_name: 'Maria',
    last_name: 'Soto',
    email: 'maria@example.com',
    external_id: 'crm-1842'
  })
};

fetch('https://api.getnexor.ai/api/public/leads/webhook?token=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getnexor.ai/api/public/leads/webhook?token=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'first_name' => 'Maria',
    'last_name' => 'Soto',
    'email' => 'maria@example.com',
    'external_id' => 'crm-1842'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getnexor.ai/api/public/leads/webhook?token="

	payload := strings.NewReader("{\n  \"first_name\": \"Maria\",\n  \"last_name\": \"Soto\",\n  \"email\": \"maria@example.com\",\n  \"external_id\": \"crm-1842\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getnexor.ai/api/public/leads/webhook?token=")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"Maria\",\n  \"last_name\": \"Soto\",\n  \"email\": \"maria@example.com\",\n  \"external_id\": \"crm-1842\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getnexor.ai/api/public/leads/webhook?token=")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"Maria\",\n  \"last_name\": \"Soto\",\n  \"email\": \"maria@example.com\",\n  \"external_id\": \"crm-1842\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "lead": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "source": "<string>",
    "metadata": {},
    "created_at": "2023-11-07T05:31:56Z",
    "last_name": "<string>",
    "email": "jsmith@example.com",
    "phone": "<string>",
    "company": "<string>",
    "title": "<string>",
    "campaign_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_to": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_user": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    }
  },
  "workflow_run": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "job_id": "<string>",
    "workflow": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    },
    "cadence": {
      "stepIndex": 123,
      "channel": "<string>",
      "attemptNumber": 123,
      "maxAttempts": 123,
      "totalSteps": 123
    }
  },
  "warning": "<string>"
}

{
  "success": true,
  "lead": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "source": "<string>",
    "metadata": {},
    "created_at": "2023-11-07T05:31:56Z",
    "last_name": "<string>",
    "email": "jsmith@example.com",
    "phone": "<string>",
    "company": "<string>",
    "title": "<string>",
    "campaign_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_to": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_user": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    }
  },
  "workflow_run": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "job_id": "<string>",
    "workflow": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    },
    "cadence": {
      "stepIndex": 123,
      "channel": "<string>",
      "attemptNumber": 123,
      "maxAttempts": 123,
      "totalSteps": 123
    }
  },
  "warning": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

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.

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.

Per-door webhook

Create and manage this door from Custom connection. Its field map uses incoming paths as keys and Nexor fields as values:

{
  "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

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.

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.

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.

Authorizations

token

string

query

required

API key passed in the query string for webhook senders that cannot set headers. Prefer X-API-Key when the sender supports custom headers.

Query Parameters

token

string

API key for senders that cannot set X-API-Key. Do not place it in logs or screenshots.

workflow_id

string<uuid>

Optional agent assignment. A workflow_id in the JSON body overrides this value.

Body

application/json

Inbound lead payload. If the API key has an intake field map, provider-specific keys are translated first and unrecognized fields may be preserved in metadata. Without a map, use the canonical fields below.

first_name

string

Lead's first name

last_name

string

Lead's last name

string<email>

Lead's email address

phone

string

Lead's phone number

company

string

title

string

city

string

date_of_birth

string<date>

external_id

string

Lead identifier in the source system

source

string

Source label. Defaults to api.

workflow_id

string<uuid>

Agent assignment. This body value overrides the query parameter.

campaign_id

string<uuid>

metadata

object

do_not_contact

boolean

Create or update the lead without starting outreach

Response

An existing lead was matched, or a configured source router intentionally skipped intake

Option 1
Option 2

success

boolean

required

Example:

true

lead

object

required

Show child attributes

workflow_run

object

Show child attributes

warning

string

Warning message if lead was created but workflow assignment failed

Last modified on September 7, 2026

Quick Start

Getting started

WhatsApp

Agents

Integrations

Account

Assistant

Advanced

Compliance

API Reference

Integrations

Leads

Agents

Workflow Tools

Knowledge Bases

Client Tools

Groups

Campaigns

Conversions

Reports

Conversations

Tags

Messages

Background Jobs

Meetings

Team

Processors

Receive leads by webhook

Choose the right endpoint

Per-door webhook

Validate without creating a lead

Generic Public API webhook

Authorizations

Query Parameters

Body

Response

​Choose the right endpoint

​Per-door webhook

​Validate without creating a lead

​Generic Public API webhook

Authorizations

Query Parameters

Body

Response

Choose the right endpoint

Per-door webhook

Validate without creating a lead

Generic Public API webhook