Webhooks

Real-time event-driven notifications for any system. Bullseye sends an HTTP POST to your endpoint when visitors are identified, so you can integrate with internal tools, custom CRMs, or any system that accepts webhooks.

Plan Requirement

Webhooks are available on Scale plans and above. If you're on Starter, Growth, or Free Trial, upgrade to Scale to enable webhooks.

Overview

• HTTP POST to your endpoint when visitors are identified

• HMAC-SHA256 signature verification for security

• Full visitor, company, and session data in the payload

• Configurable per organization

Setup

1. Log in to the Bullseye dashboard and navigate to Settings > Integrations > Webhooks

2. Click Add Webhook

3. Enter your endpoint URL (must be HTTPS)

4. Optionally configure a secret for HMAC-SHA256 signature verification

5. Select the events you want to receive (e.g., visitor.identified)

6. Save the webhook

Your endpoint must respond with a 2xx status code within 30 seconds. Non-2xx responses or timeouts trigger retries (see Retry Behavior below).

Payload Structure

Each webhook delivery includes a JSON payload with the following structure.

Event Type

The event field indicates the type of event. For visitor identification, the event is visitor.identified.

Payload Fields

Field	Description
event	Event type (e.g., visitor.identified)
timestamp	ISO 8601 timestamp when the event occurred
organization_id	Your Bullseye organization ID
session_id	Unique identifier for the visitor session
visitor	Identified visitor profile data
company	Company data associated with the visitor
session	Session metadata (pages, UTM, referrer, device)

Example Payload

{
  "event": "visitor.identified",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org_abc123",
  "session_id": "sess_xyz789",
  "visitor": {
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Smith",
    "job_title": "VP of Marketing",
    "linkedin_url": "https://linkedin.com/in/janesmith",
    "location": "San Francisco, CA"
  },
  "company": {
    "name": "Acme Corp",
    "industry": "Technology",
    "employee_count": 500,
    "location": "San Francisco, CA"
  },
  "session": {
    "landing_page": "/pricing",
    "pages_visited": ["/", "/features", "/pricing"],
    "utm_source": "google",
    "utm_medium": "cpc",
    "referrer": "https://google.com",
    "device_type": "desktop"
  }
}

HMAC-SHA256 Verification

To verify that webhook deliveries come from Bullseye, use the X-Bullseye-Signature header. The header contains an HMAC-SHA256 signature of the raw request body using your webhook secret.

Verification Steps

1. Read the raw request body (before any JSON parsing)

2. Compute HMAC-SHA256(raw_body, your_webhook_secret)

3. Encode the result as hexadecimal

4. Compare with the value in X-Bullseye-Signature

If the values match, the webhook is authentic. Reject requests where the signature does not match.

Example (Pseudocode)

signature = request.headers["X-Bullseye-Signature"]
expected = hmac_sha256_hex(request.raw_body, webhook_secret)
if signature != expected:
  return 401  # Unauthorized

Retry Behavior

If your endpoint returns a non-2xx status code or does not respond within 30 seconds, Bullseye retries the delivery:

• Retry schedule — Retries occur at increasing intervals (e.g., 1 minute, 5 minutes, 30 minutes)

• Maximum retries — Up to 3 retries per delivery

• Idempotency — The same payload may be delivered more than once; design your endpoint to handle duplicate events (e.g., using session_id as a deduplication key)

Best Practices

• Use HTTPS — Webhook endpoints must use HTTPS

• Verify the signature — Always validate X-Bullseye-Signature before processing

• Respond quickly — Return 200 immediately and process the payload asynchronously if needed

• Handle duplicates — Use session_id or a combination of fields to deduplicate events

• Log failures — Monitor for 4xx/5xx responses and fix endpoint issues promptly