Webhooks

Configure webhooks to receive real-time notifications when visitors are identified or when billing events occur. Webhooks use HMAC-SHA256 signatures for verification.

Get Webhook Configuration

Retrieve the current webhook configuration for identification and billing.

Request:

GET /partner/webhooks

Response:

{
  "identification": {
    "url": "https://example.com/webhooks/identify",
    "enabled": true,
    "hasSecret": true
  },
  "billing": {
    "url": "https://example.com/webhooks/billing",
    "enabled": true,
    "hasSecret": true
  }
}

Example:

curl -X GET "https://api.app.bullseye.so/api/v1/partner/webhooks" \
  -H "X-Partner-API-Key: your-api-key"

---

Update Identification Webhook

Configure the webhook for visitor identification events.

Request:

PUT /partner/webhooks/identification

Body:

{
  "url": "https://example.com/webhooks/identify",
  "secret": "whsec_your_webhook_secret",
  "enabled": true
}

Field	Type	Required	Description
url	string	No	Webhook endpoint URL
secret	string	No	Secret for HMAC signature verification
enabled	boolean	No	Enable or disable the webhook

Response:

{
  "identification": {
    "url": "https://example.com/webhooks/identify",
    "enabled": true,
    "hasSecret": true
  }
}

---

Update Billing Webhook

Configure the webhook for billing events.

Request:

PUT /partner/webhooks/billing

Body:

{
  "url": "https://example.com/webhooks/billing",
  "secret": "whsec_your_webhook_secret",
  "enabled": true
}

Response:

{
  "billing": {
    "url": "https://example.com/webhooks/billing",
    "enabled": true,
    "hasSecret": true
  }
}

---

Send Test Webhook

Send a test webhook to verify your endpoint is configured correctly.

Request:

POST /partner/webhooks/test

Body:

{
  "type": "identification"
}

Valid types: identification, billing

Response:

{
  "success": true,
  "message": "Test webhook sent successfully"
}

Example:

curl -X POST "https://api.app.bullseye.so/api/v1/partner/webhooks/test" \
  -H "X-Partner-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"type": "identification"}'

---

Get Webhook Logs

Retrieve webhook delivery logs for debugging and monitoring.

Request:

GET /partner/webhooks/logs

Query Parameters:

Parameter	Type	Description
page	integer	Page number
pageSize	integer	Items per page
type	string	Filter by identification or billing
status	string	Filter by delivery status
organizationId	string	Filter by organization

Response:

{
  "logs": [
    {
      "id": "uuid",
      "type": "identification",
      "organizationId": "uuid",
      "status": "delivered",
      "statusCode": 200,
      "attemptedAt": "2025-02-27T10:30:00Z",
      "responseTimeMs": 150
    }
  ],
  "total": 100,
  "page": 1,
  "pageSize": 20
}

---

Identification Webhook Payload

When a visitor is identified, your webhook receives a POST request with the following payload:

{
  "event_type": "visitor.identified",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "uuid",
  "session_id": "uuid",
  "workspace": "Org Name",
  "visitor": {
    "id": "uuid",
    "email": "[email protected]",
    "personal_email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "job_title": "CTO",
    "phone": "[phone]",
    "location": "San Francisco, CA",
    "photo_url": "https://example.com/photo.jpg",
    "linkedin_url": "https://linkedin.com/in/johndoe",
    "facebook_url": null,
    "twitter_url": null,
    "address": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "gender": null,
    "age_range": null,
    "income_range": null,
    "net_worth": null,
    "homeowner": null,
    "married": null,
    "children": null,
    "icp": "Enterprise Lead",
    "icp_statuses": {},
    "persona_match": true,
    "created_at": "2025-01-10T08:00:00Z",
    "last_seen_at": "2025-01-15T10:30:00Z"
  },
  "company": {
    "id": "uuid",
    "name": "Acme Inc",
    "domain": "acme.com",
    "industry": "Technology",
    "size": 150,
    "employee_size_range": "101-500",
    "revenue_range": "$10M-$50M",
    "linkedin_url": "https://linkedin.com/company/acme",
    "website_url": "https://acme.com",
    "description": "Enterprise software company",
    "logo_url": "https://example.com/logo.png",
    "address": "456 Business Ave",
    "city": "Austin",
    "region": "Texas",
    "postal_code": "78701"
  },
  "session": {
    "created_at": "2025-01-15T10:25:00Z",
    "landing_page": "https://acme.com/pricing",
    "entry_page": "https://acme.com",
    "exit_page": "https://acme.com/contact",
    "referrer": "https://google.com",
    "device_type": "desktop",
    "first_visit": false,
    "utm_source": "google",
    "utm_campaign": "brand",
    "utm_medium": "cpc",
    "utm_term": "visitor identification",
    "utm_content": "banner",
    "campaign_name": null,
    "campaign_source": null,
    "campaign_medium": null,
    "campaign_term": null,
    "campaign_content": null,
    "search_term": "visitor identification software",
    "search_engine": "Google",
    "country": "US",
    "region": "California",
    "city": "San Francisco",
    "tracking_params": {}
  },
  "page_views": [
    {
      "url": "https://acme.com/pricing",
      "visited_at": "2025-01-15T10:25:00Z"
    },
    {
      "url": "https://acme.com/features",
      "visited_at": "2025-01-15T10:28:00Z"
    }
  ]
}

---

Signature Verification

Webhook requests include an X-Bullseye-Signature header containing an HMAC-SHA256 signature of the raw request body.

To verify the signature:

1. Compute HMAC-SHA256 of the raw request body using your webhook secret.

2. Compare the result (hex-encoded) with the value in X-Bullseye-Signature.

Example (Node.js):

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Example (Python):

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Always use the raw request body (before JSON parsing) for signature verification. Respond with 200 OK to acknowledge receipt; non-2xx responses may trigger retries.