Skip to main content

Social Ad Webhook Integrations (Meta, Google, TikTok)

To capture leads generated directly inside social and search advertising campaigns, veridex-hitech-web-application includes webhook receivers for Meta (Facebook & Instagram) Lead Ads, Google Ads Lead Forms, and TikTok Lead Generation.

1. Meta (Facebook & Instagram) Lead Ads Pipeline​

1.1 Webhook Subscription Challenge (GET /api/webhooks/meta)​

When configuring the webhook in the Meta Developer Portal, Meta sends an initial verification handshake:

export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const mode = searchParams.get("hub.mode");
  const token = searchParams.get("hub.verify_token");
  const challenge = searchParams.get("hub.challenge");

  if (mode === "subscribe" && token === process.env.META_VERIFY_TOKEN) {
    return new Response(challenge, { status: 200 });
  }

  return new Response("Forbidden", { status: 403 });
}

1.2 Event Notification & Payload Normalization (POST /api/webhooks/meta)​

Meta event notifications contain only reference IDs. The server parses the event and initiates an authenticated background call to Meta Graph API v25.0:

GET https://graph.facebook.com/v25.0/{leadgen_id}?access_token={META_PAGE_ACCESS_TOKEN}

The Graph API returns the encrypted form answers as an array of field objects:

{
  "id": "1098273645129",
  "created_time": "2026-10-18T14:32:00+0000",
  "field_data": [
    { "name": "full_name", "values": ["David Miller"] },
    { "name": "email", "values": ["david.miller@texasfreight.net"] },
    { "name": "phone_number", "values": ["+12145554321"] },
    { "name": "city", "values": ["Dallas"] },
    { "name": "state", "values": ["TX"] },
    { "name": "what_type_of_insurance_do_you_need?", "values": ["Commercial Trucking"] }
  ]
}

The server normalizes this array into a key-value object and persists it to MetaLead with status: 'pending'.

1.3 Webhook Diagnostics & Simulation​

The platform includes built-in diagnostic and simulation endpoints:

  • GET /api/webhooks/meta/debug: Inspects recent webhook delivery logs, verification failures, and Graph API connectivity.
  • POST /api/webhooks/meta/debug: Allows administrators to simulate an incoming Meta webhook event to verify parsing logic without spending advertising budget.

2. Google Ads Lead Form Webhook (POST /api/webhook/google)​

Google Ads campaigns utilizing lead form extensions dispatch JSON payloads when users submit an inquiry directly from Google Search or YouTube ads:

  • Endpoint: POST https://hitechinsurance.ai/api/webhook/google
  • Security: Verifies the google_key query parameter or X-Goog-Signature HMAC header against GOOGLE_WEBHOOK_SECRET.
  • Payload Structure: 
    {
      "lead_id": "goog_lead_782910",
      "form_id": "form_search_commercial",
      "campaign_id": "camp_texas_trucking_01",
      "user_column_data": [
        { "column_id": "FULL_NAME", "string_value": "Robert Chen" },
        { "column_id": "USER_EMAIL", "string_value": "robert@chenhaulage.com" },
        { "column_id": "PHONE_NUMBER", "string_value": "+18325557766" },
        { "column_id": "POSTAL_CODE", "string_value": "77002" }
      ]
    }
  • Storage: Logged directly into GoogleWebhookLog with automated mapping into operational lead tables.

3. TikTok Lead Generation Webhook (GET / POST /api/webhook/tiktok)​

To capture leads generated on TikTok video ad campaigns:

  • Handshake Verification (GET /api/webhook/tiktok): Responds to TikTok's challenge parameter using TIKTOK_VERIFY_TOKEN.
  • Event Receiver (POST /api/webhook/tiktok): Receives encrypted user submission objects and queues records for agency follow-up.