> ## Documentation Index
> Fetch the complete documentation index at: https://docs.benzinga.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Overview

> Push Benzinga market data to your systems with resilient, filterable webhooks.

Benzinga webhooks eliminate polling by posting real-time market events directly to your HTTP endpoint. Deliveries are JSON `POST` requests that include a unique `X-BZ-Delivery` header for deduplication and use a tiered retry strategy to maximize reliability.

## Available webhook services

* **Data Webhook Engine**: Real-time calendar and signal data (earnings, dividends, ratings, option activity, WIIMs, and more) with configurable filters and optional payload transformations. Read the full guide in [Data Webhook Engine](./webhook-engine).
* Additional webhook configurations can be scoped to your account. Contact your Benzinga representative to enable specific datasets or to register new webhook URLs.

## Integration flow

<Steps>
  <Step title="Share your endpoint and filters">
    Provide a publicly reachable HTTPS endpoint plus any data type or geography filters you need. Benzinga will provision the webhook with those settings.
  </Step>

  <Step title="Test your integration">
    Use the [Test Webhook Delivery](/api-reference/webhook_api/test-webhook-delivery) endpoint to verify your webhook endpoint is properly configured and can receive deliveries.
  </Step>

  <Step title="Handle deliveries idempotently">
    Parse the JSON payload, use the `id` and `X-BZ-Delivery` values to avoid duplicates, and respond quickly with a 2xx status to acknowledge receipt.
  </Step>

  <Step title="Monitor and iterate">
    Track failures, timeouts, and retries in your logs. Adjust filters or payload transformations with your Benzinga contact if your downstream systems have new requirements.
  </Step>
</Steps>

## Authenticating deliveries

So your endpoint can confirm a request genuinely came from Benzinga, we can attach a credential you choose — an API key or shared token — to **every** delivery. Two placements are supported; pick whichever your stack validates most easily (or use both). These are configured per webhook when Benzinga provisions it, so share your preferred header/parameter and value with your Benzinga representative.

### API key / token in a request header

Benzinga attaches a custom header, exactly as configured, to every `POST`. Use any header name and value — for example an `Authorization` bearer token or a custom `X-API-Key`:

```http theme={null}
POST /webhook HTTP/1.1
Content-Type: application/json
Authorization: Bearer YOUR_SHARED_TOKEN
X-BZ-Delivery: 3f1c2e4a-...-9b7d

{"id":"...","api_version":"webhook/v1","kind":"...","data":{...}}
```

Validate the header on each request and reject mismatches with `401` or `403`. Benzinga **halts retries** on `401`–`403`, so only return those for genuine auth failures.

### API key / token in a query parameter

Register your delivery URL with the token baked into the query string. Benzinga posts to the exact URL you provide, so the parameter is sent on every delivery:

```
https://your-domain.com/webhook?token=YOUR_SHARED_TOKEN
```

Validate the `token` parameter (any name you choose) on each request.

<Note>
  Always use an **HTTPS** endpoint so the credential is never sent in cleartext, and treat it as a secret. A header/query token authenticates the sender; for cryptographic proof of authenticity **and** payload integrity, also verify the [HMAC signature](#verifying-deliveries-hmac-sha256) below.
</Note>

## Verifying deliveries (HMAC-SHA256)

Every delivery is signed so you can confirm it genuinely came from Benzinga and was not modified in transit. The signature is sent in the `X-Bz-Signature` header, formatted as `sha256=<hex digest>`:

```http theme={null}
POST /webhook HTTP/1.1
Content-Type: application/json
X-BZ-Delivery: 3f1c2e4a-...-9b7d
X-Bz-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

{"id":"...","api_version":"webhook/v1","kind":"...","data":{...}}
```

* **Algorithm:** HMAC-SHA256.
* **Secret:** your API key — the same key Benzinga issued you for this webhook. Keep it secret; anyone with it can forge deliveries.
* **Signed content:** the **raw request body bytes**, exactly as received.
* **Format:** `sha256=` followed by the lowercase hex digest.

To verify a delivery:

<Steps>
  <Step title="Capture the raw body">
    Read the raw request body **before** parsing or re-serializing the JSON. You must hash the exact bytes you received — a re-encoded copy will not match.
  </Step>

  <Step title="Compute the expected signature">
    Compute `HMAC-SHA256(secret = your API key, message = raw body)` and hex-encode the result.
  </Step>

  <Step title="Compare in constant time">
    Compare your value against the hex portion of `X-Bz-Signature` (after `sha256=`) using a constant-time comparison. Reject the delivery with a `4xx` if it does not match.
  </Step>
</Steps>

<Note>
  Capture the raw request body before your framework parses it. Many frameworks
  buffer and re-serialize JSON, which changes the bytes and breaks verification.
</Note>

## Best practices

* Use HTTPS and authentication on your webhook endpoint.
* Process work asynchronously so responses return within 30 seconds.
* Store processed delivery IDs to ensure idempotency across retries.
* Test against non-production endpoints before switching to live delivery.