Webhooks

Webhooks deliver real-time event notifications when visitors are identified. Configure a webhook endpoint in the Bullseye dashboard, and Bullseye sends an HTTP POST to your URL with visitor, company, and session data. Use webhooks to integrate with internal tools, custom CRMs, or any system that accepts HTTP callbacks.

Plan Requirement

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

Configuration

Webhooks are configured per organization in the Bullseye dashboard:

1. Navigate to Settings > Integrations > Webhooks

2. Click Add Webhook

3. Enter your endpoint URL (must be HTTPS)

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

5. Select the events you want to receive

6. Save the webhook

Your endpoint must respond with a 2xx status code within 30 seconds. Non-2xx responses or timeouts trigger retries.

Event Types

Event	Description
visitor.identified	Fired when a visitor is identified on your website

Payload Structure

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

Top-Level Fields

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

Visitor Object

The visitor object typically includes fields such as email, first_name, last_name, job_title, linkedin_url, location, and contact identifiers.

Company Object

The company object typically includes fields such as name, industry, employee_count, location, and domain information.

Session Object

The session object typically includes landing_page, pages_visited, utm_source, utm_medium, referrer, and device_type.

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"
  }
}

Signature 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