Webhook Integration

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:

Field Mappings

Configure which Top Provider lead fields map to specific fields in your system:

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:

Produces a flat JSON payload:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com"
}

Using dot notation in the output field names:

Produces a nested JSON payload:

{
  "contact": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com"
  }
}

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": "george.sanchez@example.com",
      "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.

Lead Updates

When a lead's availability changes on a delivered lead (for example, when they request a meeting after the lead was originally sent, or update a time they'd previously picked), Top Provider re-delivers the lead as a lead update to webhook endpoints that have the meeting time field mapped and are set to receive lead updates. Endpoints missing either piece aren't notified. The payload contains the full current lead data with the meeting field populated.

Lead update payloads include a messageType field so the receiving system can distinguish them from initial deliveries:

{
  "messageType": "lead_update",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "requestedMeetingTime": "2026-04-22T19:45:00+00:00",
  "formattedRequestedMeetingTime": "Wednesday, April 22, 2026 at 3:45 PM Eastern Daylight Time"
}

The requestedMeetingTime field is ISO 8601 in UTC for processing. The formattedRequestedMeetingTime field is a pre-formatted display string in the lead's local timezone.

Initial lead deliveries carry "messageType": "new_lead".

Endpoint Type Setting

Each webhook endpoint has a type setting in its advanced settings that controls which deliveries it receives:

Routing Patterns

• Separate URL for updates: create a second webhook endpoint with a different URL and set its type to Lead updates only.
• Single endpoint for both: set the endpoint type to New leads and lead updates and branch on messageType server-side.
• No update deliveries (useful when the receiving system can't handle re-deliveries): leave the endpoint at New leads only.

See Meeting Requests for the full cross-channel behavior.

Testing Your Configuration

Verify your webhook is working correctly:

Common Issues & Solutions

FAQ