Webhook Lead Sources

Overview

Webhook lead sources allow external systems to send leads directly into brayv.ai via HTTP webhooks. When your external system sends data to your webhook URL, brayv.ai automatically creates or updates contacts and can enroll them in journeys.

Webhooks are perfect for:

• Integrating with third-party lead generation platforms
• Integrating with third-party web form providers (JotForm, TypeForm, etc.)
• Connecting other CRMs or marketing tools
• Using automation platforms (Zapier, Make, n8n)
• Custom integrations from your own systems
• Lead aggregator services (Angi Leads, Angi Ads, Thumbtack, etc.)

Step by step walkthrough video of creating a webhook lead source

Creating a Webhook Lead Source

Step 1: Go to Settings > Lead Sources

Step 2: In the "Add New Source" section, click Webhook

Step 3: Enter a Name for your webhook

• Internal name to identify this webhook
• Example: "Zapier Integration", "Angi Leads", "Jotform, Main Contact Form"

Step 4: Click "Create"

Step 5: You'll be redirected to a page showing you the webhook URL

Webhook URL

After creating a webhook, you'll receive a unique webhook URL:

https://api.brayv.ai/lead-sources/webhooks/leads/[WEBHOOK_ID]

This URL:

• Is unique to this webhook source
• Accepts POST requests with JSON payloads
• Never expires
• Can be deactivated if compromised (contact support)

Share this URL with:

• Your automation platform (Zapier, Make, etc.)
• External systems sending you leads (i.e. enter this webhook URL in your form provider as the destination for submissions)
• Your development team for custom integrations

Field Mapping

Field mapping tells brayv.ai how to translate incoming webhook data into contact fields.

Understanding Field Mapping

Source Field - The field name in the incoming webhook payload

Target Field - The brayv.ai contact field it maps to

Example:

• Incoming data has customer_name → Map to full_name
• Incoming data has phone_number → Map to phone
• Incoming data has zip → Map to zip_code

Setting Up Field Mappings

Step 1: Send a Test Payload

Before you can map fields, send a test webhook with sample data:

1. Use your external system to send a test lead (for example, send a test with Zapier, or submit your JotForm after entering the webhook URL)
2. Or use a tool like Postman/cURL to send test data, for example:

curl -X POST https://api.brayv.ai/lead-sources/webhooks/leads/[WEBHOOK_ID] \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "phone": "5551234567",
    "email": "[email protected]",
    "service_requested": "HVAC Repair"
  }'

3. Click "Check for Test Lead"
4. Once brayv.ai receives the payload, you can move on to mapping.

Step 2: Review Detected Fields

After sending a test payload:

• brayv.ai will detect all fields in the payload
• You'll see a list of source fields to map

Step 3: Map Each Field

For each source field:

1. Select the corresponding brayv.ai contact field from the dropdown
2. Or leave unmapped if you don't need that data

Available Target Fields:

• Standard contact fields (first_name, last_name, email, phone, etc.)
• Custom fields you've created

Step 4: Save Mappings

Click "Save Mappings" to activate the webhook

Payload Format Requirements

Phone Number Format:

• Must be 10 digits (US/Canada)
• Can include formatting, system will strip it: (555) 123-4567 → 5551234567
• Do not include country code +1

Email Format:

• Standard email format: [email protected]
• Must include @ and domain

Other Fields:

• Text fields: Any string value
• Date fields: ISO format preferred (YYYY-MM-DD)
• Boolean fields: true/false, yes/no, 1/0

Reconfiguring mapping

• You can reconfigure your mapping at any time
• After the webhook is saved, just click into it from the Lead Sources page
• You can see the currently mapped payload (data structure brayv.ai is expecting)
• You can see and change the mapping (webhook data → brayv.ai field)
• If your payload structure has changed since your intitial setup, you can select the most recent payload to use for mapping.
• Be sure to save when you are done

Journey Enrollment Rules

Control which contacts get added to which journeys based on webhook data.

Basic Enrollment:

Add All to Journey:

• Enable journey enrollment
• Select a journey as default
• All webhook submissions go to that journey

Conditional Enrollment (Rules):

Route contacts to different journeys based on webhook data.

To Set Up Rules:

1. Go to the "Journey" tab
2. Click "Add Rule"
3. Select which field to evaluate
4. Choose condition (equals, contains, etc.)
5. Enter value to match
6. Select journey to enroll in
7. Set rule order/priority
8. Leads not matching a rule will go to the default journey

Rule Configuration:

• Field - Which incoming field to check
• Condition - equals, not_equals, contains, starts_with, ends_with
• Value - Value to match
• Journey - Journey to enroll contact in
• Order - First matching rule wins

Example:

If service_type equals "HVAC" → Add to HVAC Journey
If service_type equals "Plumbing" → Add to Plumbing Journey  
Otherwise → Add to General Service Journey

Contact Field Settings

Configure default values for contact fields from webhook submissions.

Friendly Source

• Human-readable description of where the contact came from
• Used by AI agents in conversations
• Example: "Angi", "our Facebook Ad", "our website"
• Highly Recommended - Helps AI personalize conversations

Hook Mode "Hook" is a short, general description of what your contact is interested in

Don't Set Hook - Leave hook field blank (not recommended if adding leads to a journey)

Static Text - Same hook for all webhook submissions

• Example: "HVAC services", "home improvement"
• Use when all submissions are about the same thing

From Field - Pull hook from a webhook field

• Select which incoming field contains the hook
• Example: If webhook includes service_requested, use that
• Recommended - Most flexible

Notification Settings

Get notified when webhook leads are received.

Enable Notifications

• Toggle to turn on notifications
• Select team members to notify
• Choose notification channels (Email, In-App)

Useful For:

• High-value lead sources
• New integration monitoring
• You want to know when a new lead comes in

Webhook History

View all webhook submissions received.

Access: Webhook details page > History tab

What You See:

• Timestamp of each submission
• Full payload received
• Whether processing succeeded or failed
• Which contact was created/updated
• Any error messages

Use For:

• Debugging field mapping issues
• Verifying data is coming through correctly
• Troubleshooting failures
• Monitoring webhook activity
• Compliance records (if your webhooks include opt-in data, it will be preserved in the submission history - does not need to be saved to any contact field)

How Webhook Submissions Work

Processing Flow

1. External system sends POST request to webhook URL
2. brayv.ai receives and validates JSON payload
3. Field mappings are applied
4. Contact matching by phone number
5. Contact created or updated
6. Friendly source and hook applied
7. Journey enrollment rules evaluated
8. Contact added to journey (if applicable)
9. Notifications sent (if enabled)

Contact Matching

If phone number matches existing contact:

• Contact is updated with new data
• Fields are updated with new values
• No duplicate created

If phone number doesn't match:

• New contact is created
• All mapped fields are saved

Note: Matching is by phone number only. Emails are not used for matching.

Response Codes

200 Success

{
  "status": "success",
  "contact_id": "[CONTACT_ID]",
  "message": "Contact created/updated successfully"
}

400 Bad Request

• Invalid JSON payload
• Missing required fields
• Invalid field format

500 Server Error

• Internal processing error
• Check webhook history for details

Common Integration Scenarios

Zapier Integration

Step 1: Create webhook in brayv.ai

Step 2: In Zapier, add "Webhooks by Zapier" action

Step 3: Choose "POST"

Step 4: Enter your brayv.ai webhook URL

Step 5: Set payload format to JSON

Step 6: Map your Zap data to JSON fields:

{
  "first_name": "{{FirstName}}",
  "last_name": "{{LastName}}",
  "phone": "{{Phone}}",
  "email": "{{Email}}",
  "service_requested": "{{Service}}"
}

Step 7: Test the Zap

Step 8: Map fields in brayv.ai

Make (Integromat) Integration

Step 1: Create webhook in brayv.ai

Step 2: Add HTTP module in Make

Step 3: Choose "Make a request"

Step 4: Set Method to POST

Step 5: Enter webhook URL

Step 6: Set Body type to "Raw"

Step 7: Add JSON payload with your data

Step 8: Test and map fields in brayv.ai

Custom API Integration

Send POST requests from your application:

// JavaScript/Node.js example
const response = await fetch('YOUR_WEBHOOK_URL', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'John',
    last_name: 'Doe',
    phone: '5551234567',
    email: '[email protected]',
    custom_field: 'value'
  })
});

const result = await response.json();
console.log(result);

# Python example
import requests

payload = {
    'first_name': 'John',
    'last_name': 'Doe',
    'phone': '5551234567',
    'email': '[email protected]',
    'custom_field': 'value'
}

response = requests.post(
    'YOUR_WEBHOOK_URL',
    json=payload
)

print(response.json())

Lead Aggregator Integration

Many lead aggregators (Angi, HomeAdvisor, Thumbtack) can send leads via webhooks:

Step 1: Contact the aggregator's support

Step 2: Request webhook/API integration

Step 3: Provide your brayv.ai webhook URL (Most of them will send you a test lead, otherwise they will refer you to their data format)

Step 4: Ask for their payload format/documentation

Step 5: Send test lead from aggregator (if they do not offer sending test leads, brayv.ai support is happy to help you generate a test lead with their format - eg, typically needed with thumbtack)

Step 6: Map fields in brayv.ai

Step 7: Configure journey enrollment for aggregator leads

Best Practices

Always Configure Friendly Source

Set friendly source to identify the lead origin:

• "Angi"
• "Thumbtack"
• "Our website"
• "HomeAdvisor"

This helps AI agents reference the source in conversations in a way the contact understands.

Use Hook from Field When Possible

If incoming webhook data includes what the customer wants:

• Map it to a field
• Set hook mode to "From Field"
• This gives AI agents context about customer intent

Test Thoroughly

Before Going Live:

1. Send multiple test payloads
2. Verify contacts are created correctly
3. Check field mappings are accurate
4. Test journey enrollment rules
5. Confirm notifications work

Monitor Webhook History

Regularly check webhook history:

• Verify submissions are processing successfully
• Catch field mapping issues early
• Monitor for spam or invalid data
• Track lead volume from each source

Set Up Journey Enrollment

Don't just create contacts - route them into journeys:

• Leads get immediate AI engagement
• Automated follow-up begins instantly
• Higher conversion rates

Use Conditional Rules for Multiple Lead Types

If your webhook receives different types of leads:

• Set up journey enrollment rules
• Route leads to appropriate journeys
• Ensure right AI agent handles each type

Keep Webhook URLs Secure

Treat webhook URLs like passwords:

• Don't share publicly
• Only give to trusted systems
• Monitor for unusual activity
• Contact support if compromised

Troubleshooting

Problem: Webhook not receiving data

Solution:

• Verify the webhook URL is correct
• Check that external system is sending POST requests
• Ensure Content-Type header is set to application/json
• Test with cURL or Postman first
• Check webhook history for any received attempts

Problem: Contacts not being created

Solution:

• Check webhook history for error messages
• Verify phone number is in correct format (10 digits)
• Ensure required fields are mapped
• Check that mapped fields have data in payload
• Verify JSON payload is valid

Problem: Field mappings not working

Solution:

• Send a fresh test payload
• Verify source field names exactly match payload
• Check for typos in field names (case-sensitive)
• Ensure payload structure matches what you mapped
• Try refreshing field mappings

Problem: Wrong data in contact fields

Solution:

• Review field mappings
• Verify source → target mapping is correct
• Check incoming payload structure
• Remap fields if needed
• Test with a new submission

Problem: Contacts not added to journey

Solution:

• Verify journey enrollment is enabled
• Check that journey rules are configured
• Ensure journey exists and is active
• Review rule conditions (exact matching required)
• Check that evaluated field has data in payload

Problem: Getting duplicate contacts

Solution:

• Verify phone numbers in payloads are consistent
• Check that phone field is mapped
• Ensure phone numbers are 10 digits
• Review recent contacts for duplicates
• Phone is the only matching field - emails don't prevent duplicates

Problem: Notifications not sending

Solution:

• Verify notifications are enabled
• Check that users are selected
• Ensure team members have valid email addresses
• Check spam folder for email notifications (if you receive in spam, explicitly mark as NOT SPAM, so your email provider knows you want to receive these emails)
• Verify notification channels are enabled

Related Features

• Customer Journeys - Automatically route webhook leads into journeys
• Forms - Alternative lead capture method
• Managing Contacts - View and manage contacts created from webhooks