# 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

```json
{
  "event": "visitor.identified",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org_abc123",
  "session_id": "sess_xyz789",
  "visitor": {
    "email": "jane.smith@acme.com",
    "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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bullseye.so/integrations/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.