Logo

Webhook Integration

Integrate Top Provider leads directly into your systems using real-time webhook notifications

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

Navigation to Delivery Settings

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.

Create Webhook Endpoint

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 from JSON (recommended), XML, Form, or HubSpot Forms API
  • 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.

Structured Field Names

When using JSON output format, dot notation in output field names produces nested objects in the payload. This is useful for matching the data structure expected by your receiving system.

For example, using flat field names:

Top Provider FieldOutput Field Name
First NamefirstName
Last NamelastName
Email Addressemail

Produces a flat JSON payload:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]"
}

Using dot notation in the output field names:

Top Provider FieldOutput Field Name
First Namecontact.firstName
Last Namecontact.lastName
Email Addresscontact.email

Produces a nested JSON payload:

{
  "contact": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]"
  }
}

Multiple levels of nesting are supported (e.g., data.contact.name.first). Structured field names only apply to the JSON output format.

HubSpot Forms API Output

The HubSpot Forms API output format generates payloads compatible with the HubSpot Forms v3 API. Each mapped field is structured as an object with name, value, and objectTypeId properties. The payload also includes a WEBHOOKURL property containing the configured endpoint URL.

Example payload:

{
  "fields": [
    {
      "name": "firstname",
      "value": "George",
      "objectTypeId": "0-1"
    },
    {
      "name": "lastname",
      "value": "Sanchez",
      "objectTypeId": "0-1"
    },
    {
      "name": "email",
      "value": "[email protected]",
      "objectTypeId": "0-1"
    },
    {
      "name": "jobtitle",
      "value": "HR Specialist",
      "objectTypeId": "0-1"
    },
    {
      "name": "company",
      "value": "Acme Corp",
      "objectTypeId": "0-1"
    },
    {
      "name": "message",
      "value": "Looking for background check services for our team.",
      "objectTypeId": "0-1"
    }
  ],
  "WEBHOOKURL": "https://api.hsforms.com/submissions/v3/integration/submit/..."
}

The objectTypeId of "0-1" corresponds to HubSpot Contacts. The name values correspond to HubSpot property internal names as configured in your field mappings.

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 "Send test" 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.

Common Issues & Solutions

IssueSolution
Connection issuesEnsure your webhook URL is publicly accessible, verify there are no firewalls blocking incoming connections
Authentication errorsVerify that authentication tokens or API keys are correctly formatted in your headers
Field mapping errorsEnsure field names exactly match what your external system expects, check for typos
TimeoutsOptimize your endpoint to respond quickly, implement asynchronous processing
HTTP error codesCheck error messages in the notification history for specific guidance

FAQ

HubSpot Integration
Connect Top Provider with HubSpot to automatically create/augment Contact and post timeline events
Lead Fields Reference
Complete reference guide for all lead fields available in Top Provider integrations