Skip to main content

Receive Lead via Webhook

Push a lead into Superfone by POSTing a JSON payload to your integration's webhook URL. The endpoint matches by phone number — if a lead with that phone already exists in your account, it's updated; otherwise a new lead is created and round-robin assigned.

The webhook_uuid in the URL is the credential — there's no separate signature or API key. The request is processed synchronously: the response tells you the outcome (new vs. updated lead, assigned agent) directly. Get the webhook URL from the integration's settings in the Superfone dashboard.

Server-to-server recommended

CORS is allowed, so browser calls won't be blocked at the network layer — but the webhook URL should never be shipped to a browser, since knowing it is enough to push leads into your account. Make all requests from your backend. See Overview for the full security model.

HTTP Request​

POST /webhook/integration/:webhook_uuid

Path Parameters​

ParameterTypeRequiredDescription
webhook_uuidstringYesThe unique identifier issued when you created the integration in the dashboard.

Required Headers​

HeaderDescription
content-typeMust be application/json.

Request Body​

FieldTypeRequiredDescription
customer_phonestringYesLead's phone number (E.164 preferred, e.g. +918000000001). Used to match an existing lead or create a new one.
first_namestringNoLead's first name. Existing leads keep their stored first/last name if the incoming first_name looks like a phone number.
last_namestringNoLead's last name.
emailstring | string[]NoOne or more email addresses. A single string is accepted and converted to a one-element array.
addressstring | objectNoAddress. A plain string is stored as { "text": "..." }; an object is stored as-is. See Address object.
websitestringNoLead's website.
citystringNoCity name.
business_namestringNoLead's business or company name.
additional_infostringNoFree-form notes / additional info on the lead.
deal_valuenumberNoEstimated deal value.
sourcestringNoFree-form source string (e.g. "facebook-leadgen", "landing-page"). Falls back to the integration's configured source.
source_typestringNoOne of the predefined source types. See List source types. Falls back to the integration's configured source_type.
assignee_user_idnumberNoID of a Superfone team member to assign the lead to. If omitted, the lead is round-robin assigned across the integration's configured assignee_user_ids.
lead_stage_idnumberNoID of a lead stage. Falls back to the integration's configured stage.
lead_group_idnumberNoID of a lead group. Falls back to the integration's configured group.
label_idsnumber[]NoIDs of labels to attach. Falls back to the integration's configured labels.
(custom field label name)string | numberNoAny custom field configured on your account — see Custom fields.

Address object​

FieldTypeDescription
textstring | nullFree-form address text
additionalstring | nullApartment / unit / additional line
initialsstring | nullAddress initials (used for display)
latitudenumber | nullLatitude
longitudenumber | nullLongitude

If you pass a plain string for address, it's stored as { "text": "<your string>" }.

Field-fallback behavior​

For lead_stage_id, lead_group_id, label_ids, source, and source_type: if the field is omitted from the payload, the value configured on the integration setting is used. For assignee_user_id: when omitted, the lead is round-robin assigned across the integration's configured assignee_user_ids pool. This lets you keep payloads minimal — only include a field when you want to override the integration's default.

Custom fields​

Send a custom field by its configured label/title from your account's custom field settings as a top-level key (e.g. "Course": "MBA"). It's resolved to the right field automatically based on that label's type.

{
  "customer_phone": "+918000000001",
  "Course": "MBA",
  "Budget": 50000
}

Type-specific behavior when resolving a label:

Label typeBehavior
DropdownValue is matched against the label's configured allowed values (case/space/underscore-insensitive). No match → the field is left unset.
Date / Date-timeParsed in the org's timezone. An unparseable value → the field is left unset.
NumericParsed as an integer. A non-numeric value → the field is left unset.
Text (and others)Used as-is.

A text-type custom field value that's an object or array is dropped rather than saved.

Try it​

Paste your integration's webhook UUID below and click Send (or Copy as cURL to run it from your terminal).

Loading playground…

Code Examples​

#!/usr/bin/env bash
set -euo pipefail

WEBHOOK_UUID="8f4e2a31-2b6d-4c3a-9f1e-7a0b6c2d4e5f"
URL="https://prod-api.superfone.co.in/superfone/webhook/integration/${WEBHOOK_UUID}"

curl -X POST "$URL" \
  -H "content-type: application/json" \
  --data '{"customer_phone":"+918000000001","first_name":"Asha","last_name":"Kumar","email":"asha@example.com","business_name":"Acme Pvt Ltd","city":"Bengaluru","address":"12 MG Road, Bengaluru","deal_value":50000,"source":"landing-page","additional_info":"Asked for a callback after 6 PM."}'

Success Response​

Status Code: 200 OK

{
  "data": {
    "is_new_customer": true,
    "customers": [{ "id": 123456, "first_name": "Asha", "last_name": "Kumar", "..." : "..." }],
    "agent_name": "Ravi Shankar",
    "agent_phone": "+919000000002",
    "agent_superfone": "+918040000000",
    "group_request_id": "a1b2c3d4e5f6",
    "customer_id": 123456,
    "task_id": 789012
  },
  "message": "success"
}

Response Fields​

FieldTypeDescription
data.is_new_customerbooleantrue if this call created a new lead, false if it updated an existing one.
data.customersarrayThe affected lead record(s) — the newly created lead, or the matched existing lead(s).
data.agent_namestringName of the team member the lead was assigned to (empty if unassigned).
data.agent_phonestringAssigned agent's phone number.
data.agent_superfonestringThe Superfone number associated with the account.
data.group_request_idstringServer-side trace ID for this request. Quote it in any support request about a specific delivery.
data.customer_idnumberID of the lead that was created or updated by this api call.
data.task_idnumberID of the task created for this lead, if a task was configured on the integration. Omitted if no task was created.
messagestring"success" on a 200.

Error Responses​

Errors are returned synchronously — there's no separate log to check after the fact.

StatusWhen it occurs
400Request body is empty, or no valid phone number was found in customer_phone.
404webhook_uuid doesn't match a configured integration, no active subscription/CRM addon on the account, or the account's lead storage is full.
500Unexpected server error. Safe to retry.

Example error​

{
  "message": "No valid phone numbers found in payload"
}

Retries​

There's no idempotency key on this endpoint. If a request times out or you get a 5xx, a retry is safe to send — the endpoint always re-resolves the lead by phone, so retrying an update just re-applies the same values. Avoid firing the same payload multiple times from a source that doesn't dedupe on its own, since a matched follow-up task can be re-created on every call.