Webhook Integration
Integrate Top Provider leads directly into your systems using real-time webhook notifications
Why Choose Webhook Integration?
Ideal for technical teams who want complete control over lead data and custom integrations with their existing systems or proprietary applications.
Webhook Integration Overview
The Top Provider Webhook Integration enables real-time lead delivery directly to your systems through secure HTTP notifications. This developer-focused integration offers:
- Instant Data Delivery: Receive leads the moment they're assigned
- Flexible Implementation: Works with any system that can receive HTTP requests
- Maximum Control: Process leads according to your specific business rules
- Seamless CRM Integration: Connect to any CRM or internal system
Prerequisites
Before setting up a webhook integration, you will need:
- An external system capable of receiving webhook HTTP requests
- A publicly accessible URL endpoint to receive the data
- Access to the Seller Portal with appropriate permissions to manage integrations
- Knowledge of which lead fields you want to include in your webhook payload
- Understanding of your target system's data format requirements (JSON, XML, etc.)
Quick Setup Guide
Setting up webhook integration takes just a few steps:
Prepare Your Endpoint
Create an HTTP endpoint on your server that can:
- Accept POST requests
- Process JSON payloads
- Return appropriate HTTP status codes (200/201/202 for success)
Access Delivery Settings
Sign in to the Seller Portal and navigate to Delivery Settings in the left sidebar.
Alternatively, you can navigate directly to: /delivery
Create Webhook Endpoint
On the Delivery Settings page, locate and click the "+ Add a webhook" button. This will open a modal dialog to configure your webhook.
Configure Your Webhook
Enter the following information:
- Name: A descriptive name for your webhook (e.g., "CRM Integration", "Lead API Endpoint")
- Webhook URL: The full URL of your endpoint (must be publicly accessible)
- Data Format: Choose JSON (recommended), XML, or Form
- HTTP Headers (Optional): Add authentication or custom headers
- Constants (Optional): Add key-value pairs to include with every lead
Lead Order Selection (Optional)
- Click "Attached Lead Orders" to expand the section
- Select specific lead orders to associate with this webhook
- The webhook will receive leads from all lead orders by default
Complete Setup
After entering all required information, click "Save" to create your webhook endpoint.
Field Mappings
Configure which Top Provider lead fields map to specific fields in your system:
Access Field Mappings
Once the webhook is created, click on "Details" to access the webhook details page, then click the "Settings" button. In the Settings modal, click "Adjust Field Mappings" to expand the section.
Configure Standard Mappings
For each field, enter the corresponding field name for your external system.
Add Additional Mappings
Under "Available Fields," you can add more field mappings as needed. Click on any field in the "Available Fields" section to add it to your mappings. Use exact field names expected by your external system.
Save Your Mappings
After configuring all your field mappings, click "Save" to apply the changes. The webhook will now use these mappings when sending data.
For a complete list of all available lead fields and detailed specifications, see our Lead Fields Reference.
Testing Your Configuration
Verify your webhook is working correctly:
Access Endpoint Details
Go to your created webhook and click "Details" to access the webhook details page
Test the Endpoint
Locate the "Test Endpoint" button and click it to send a test lead to your webhook URL. You'll receive feedback on whether the test was successful.
View Notification History
Click on "Notification History" in the tab navigation to review delivery details:
- Timestamps of delivery attempts
- Status (Success/Failure)
- HTTP response codes
- Error messages (if any)
Check Your System
Log in to your external system and verify that the test data was received properly. Confirm that all mapped fields contain the expected data.
Test leads use sample data to verify connectivity. If the test lead doesn't appear in your system, check the notification history for error messages.
Common Issues & Solutions
| Issue | Solution |
|---|---|
| Connection issues | Ensure your webhook URL is publicly accessible, verify there are no firewalls blocking incoming connections |
| Authentication errors | Verify that authentication tokens or API keys are correctly formatted in your headers |
| Field mapping errors | Ensure field names exactly match what your external system expects, check for typos |
| Timeouts | Optimize your endpoint to respond quickly, implement asynchronous processing |
| HTTP error codes | Check error messages in the notification history for specific guidance |
Need help? Contact our support team at support@topprovider.com if you need assistance.