Inbound Webhook Payload Reference
Use this guide to understand the data SalesAi accepts through inbound webhooks when creating and enrolling contacts. This reference is intended for developers, integration specialists, and CRM administrators building integrations with SalesAi.
Recommended Flow
CRM / Form / Middleware → SalesAi Inbound Webhook
Common sources include:
- HubSpot
- Salesforce
- GoHighLevel
- Zapier
- n8n
- Make
- Website Forms
- Custom Applications
The inbound webhook creates or updates the contact and enrolls them into the configured SalesAi workflow.
Required FieldsSalesAi recommends sending the following fields with every contact.
|
Field |
Description |
|
first_name |
Contact first name |
|
last_name |
Contact last name |
|
|
Contact email address |
|
phone_number |
Contact phone number |
Example
{
"first_name": "Otto",
"last_name": "Naser",
"email": "otto@example.com",
"phone_number": "7087156080"
}
Optional Fields
The following fields may be included to provide additional context for the AI agent.
|
Field |
Description |
|
linkedin_url |
LinkedIn profile URL |
|
job_title |
Contact job title |
|
department |
Contact department |
|
seniority_level |
Contact seniority level |
|
address_city |
Contact city |
|
address_state |
Contact state |
|
address_postal_code |
Postal / ZIP code |
|
address_country |
Country |
|
pain_points |
Prospect pain points |
|
decision_timeframe |
Expected buying timeline |
|
consent |
Boolean value indicating consent |
|
lead_source |
Source of the lead |
Example
{
"first_name": "Otto",
"last_name": "Naser",
"email": "otto@example.com",
"phone_number": "7087156080",
"job_title": "Owner",
"lead_source": "Website Form",
"address_city": "Chicago",
"address_state": "Illinois"
}
Phone Number Formatting
Phone numbers should be sent as valid 10-digit values.
Valid Examples
7087156080
3125551234
Invalid Examples
(708) 715-6080
+1 708 715 6080
708-715-6080
Invalid phone formatting may prevent successful enrollment.
Custom FieldsSalesAi supports custom fields using two formats.
Method 1: Nested Custom Fields
Custom fields can be passed inside a custom_fields object.
{
"first_name": "Otto",
"last_name": "Naser",
"email": "otto@example.com",
"phone_number": "7087156080",
"custom_fields": {
"field1": "value1",
"field2": "value2"
}
}
This is the recommended approach when your integration platform supports nested JSON objects.
Method 2: Flattened Custom Fields
Custom fields can also be passed using double underscore notation.
{
"first_name": "Otto",
"last_name": "Naser",
"email": "otto@example.com",
"phone_number": "7087156080",
"custom_fields__field1": "value1",
"custom_fields__field2": "value2"
}
This format is commonly used when the integration platform does not support nested JSON objects.
Examples include:
- Zapier
- Some CRM webhook actions
- Certain form builders
- Legacy integration platforms
{
"first_name": "Otto",
"last_name": "Naser",
"email": "otto@example.com",
"phone_number": "7087156080",
"linkedin_url": "https://linkedin.com/in/ottonaser",
"job_title": "Owner",
"department": "Sales",
"seniority_level": "Executive",
"address_city": "Chicago",
"address_state": "Illinois",
"address_postal_code": "60453",
"address_country": "USA",
"lead_source": "Website Form",
"custom_fields": {
"vehicle_interest": "Cullinan",
"lead_type": "Prom Rental"
}
}
Authentication Requirements
SalesAi inbound webhooks require a shared secret header for authentication.
|
Header Name |
Description |
|
X-SalesAi-Webhook-Shared-Secret |
SalesAi shared secret |
Example Header
X-SalesAi-Webhook-Shared-Secret: your-shared-secret
Requests missing this header may be rejected.
Common Validation Issues|
Issue |
Resolution |
|
Missing first_name |
Populate first_name |
|
Missing last_name |
Populate last_name |
|
Missing email |
Populate email |
|
Missing phone_number |
Populate phone_number |
|
Invalid phone number format |
Use a valid 10-digit phone number |
|
Missing authentication header |
Add X-SalesAi-Webhook-Shared-Secret |
|
Invalid shared secret |
Verify the secret matches SalesAi |
|
Incorrect custom field formatting |
Use nested or flattened format |
Recommended Minimum Payload
For most integrations, SalesAi recommends sending:
{
"first_name": "Otto",
"last_name": "Naser",
"email": "otto@example.com",
"phone_number": "7087156080"
}
This provides enough information for contact creation and workflow enrollment.
Best Practices
When building inbound webhook integrations:
- Always send first_name.
- Always send last_name.
- Always send email.
- Always send phone_number.
- Use valid 10-digit phone numbers.
- Include lead_source when available.
- Pass custom fields for personalization.
- Test payloads before publishing.
- Verify authentication headers are configured
Final Validation
Before moving an integration into production:
- Confirm the webhook URL is correct.
- Confirm the request method is POST.
- Confirm required fields are populated.
- Confirm phone numbers are formatted correctly.
- Confirm authentication headers are configured.
- Validate custom field mappings.
- Run a successful test enrollment.
- Verify the contact appears in SalesAi.
Once validation is complete, the integration is ready for production use.