Webhooks API

Use the Webhooks API to export visitor profiles to external systems and messaging tools.

🌐 Endpoints

GET/api/webhook

Return supported webhook types and a reference payload for POST requests.

🔑 Authentication required: Yes, via session cookie.

Example Request

Bash

curl --request GET \
  --url https://analytics.ghostid.ai/api/webhook \
  --cookie "session=YOUR_SESSION_COOKIE"

Response Example

JSON

{
  "supported_types": ["custom", "hubspot", "salesforce", "slack", "discord"],
  "example_payload": {
    "ghost_vid": "gv_xxx",
    "webhook_url": "https://your-webhook.com/endpoint",
    "webhook_type": "custom",
    "include_journey": true,
    "include_events": true,
    "siteId": 4
  }
}

POST/api/webhook

Send visitor data to an external webhook target.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
ghost_vid	string	Yes	Visitor ID to export.
webhook_url	string	Yes	Destination webhook URL.
webhook_type	string	No	One of custom, hubspot, salesforce, slack, or discord.
include_journey	boolean	No	Include recent session journey data. Defaults to true.
include_events	boolean	No	Include recent event activity. Defaults to true.
siteId	number	No	Site that owns the visitor. Defaults to 4 if omitted.

Request Body

JSON

{
  "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
  "webhook_url": "https://example.com/hooks/leads",
  "webhook_type": "custom",
  "include_journey": true,
  "include_events": true,
  "siteId": 4
}

Example Request

Bash

curl --request POST \
  --url https://analytics.ghostid.ai/api/webhook \
  --cookie "session=YOUR_SESSION_COOKIE" \
  --header "Content-Type: application/json" \
  --data '{
    "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
    "webhook_url": "https://example.com/hooks/leads",
    "webhook_type": "custom",
    "include_journey": true,
    "include_events": true,
    "siteId": 4
  }'

Response Example

JSON

{
  "success": true,
  "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
  "webhook_type": "custom",
  "delivered_at": "2026-03-10T17:18:00.000Z"
}

📦 Webhook Payloads

custom

JSON

{
  "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
  "score": 65,
  "status": "identified",
  "identified_user_id": "jane@example.com",
  "location": {
    "country": "United States",
    "city": "Austin"
  },
  "device": {
    "type": "desktop",
    "browser": "Chrome"
  },
  "engagement": {
    "total_sessions": 3,
    "total_pageviews": 11,
    "total_time_seconds": 421,
    "first_seen": "2026-03-02T09:12:11.000Z",
    "last_seen": "2026-03-10T17:14:22.000Z"
  },
  "journey": [
    {
      "session_id": "gs_123",
      "started_at": "2026-03-10T17:09:10.000Z",
      "ended_at": "2026-03-10T17:14:22.000Z",
      "pageview_count": 5,
      "entry_page": "/",
      "exit_page": "/pricing",
      "referrer": "https://google.com"
    }
  ],
  "recent_events": [
    {
      "type": "pageview",
      "page": "/pricing",
      "timestamp": "2026-03-10T17:14:22.000Z"
    }
  ],
  "links": {
    "profile": "https://analytics.ghostid.ai/visitor/gv_a1b2c3d4_e5f6g7h8",
    "connect": "https://analytics.ghostid.ai/talk/incoming?visitor=gv_a1b2c3d4_e5f6g7h8"
  },
  "exported_at": "2026-03-10T17:18:00.000Z"
}

hubspot

JSON

{
  "properties": {
    "ghost_visitor_id": "gv_a1b2c3d4_e5f6g7h8",
    "email": "jane@example.com",
    "city": "Austin",
    "country": "United States",
    "hs_analytics_source": "GHOST",
    "ghost_score": "65",
    "ghost_sessions": "3",
    "ghost_pageviews": "11",
    "ghost_first_seen": "2026-03-02T09:12:11.000Z",
    "ghost_last_seen": "2026-03-10T17:14:22.000Z"
  }
}

salesforce

JSON

{
  "Ghost_Visitor_ID__c": "gv_a1b2c3d4_e5f6g7h8",
  "Email": "jane@example.com",
  "City": "Austin",
  "Country": "United States",
  "LeadSource": "GHOST Visitor Intelligence",
  "Ghost_Score__c": 65,
  "Ghost_Sessions__c": 3,
  "Ghost_Pageviews__c": 11
}

slack

JSON

{
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "New Lead from GHOST"
      }
    },
    {
      "type": "section",
      "fields": [
        { "type": "mrkdwn", "text": "*Visitor ID:*\ngv_a1b2c3d4_e5f6g7h8" },
        { "type": "mrkdwn", "text": "*Score:*\n65/100" },
        { "type": "mrkdwn", "text": "*Location:*\nAustin, United States" },
        { "type": "mrkdwn", "text": "*Sessions:*\n3" }
      ]
    }
  ]
}

discord

Discord is supported as a webhook type. Use the same request body shape as other webhook deliveries and provide a Discord-compatible webhook URL.

JSON

{
  "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
  "score": 65,
  "status": "identified",
  "identified_user_id": "jane@example.com",
  "location": {
    "country": "United States",
    "city": "Austin"
  },
  "engagement": {
    "total_sessions": 3,
    "total_pageviews": 11,
    "total_time_seconds": 421
  },
  "recent_events": [
    {
      "type": "pageview",
      "page": "/pricing",
      "timestamp": "2026-03-10T17:14:22.000Z"
    }
  ]
}

Revenue

Identify