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

# Webhooks

> Register outbound webhooks for whale entries and arbitrage opportunities.

Receive push notifications instead of polling the [Whale tracking](/api-reference/whales-overview)
feed or [Arbitrage](/api-reference/arbitrage-current) scanner. Each customer may register
**one webhook per type**: `whale` and `arbitrage`.

All routes require an API key — see [Authentication](/authentication).

## Plan requirements

| Type        | Required plan     |
| ----------- | ----------------- |
| `whale`     | Builder or Trader |
| `arbitrage` | Trader            |

Registering or updating below the required plan returns **403** with an entitlement
message naming the plan you need.

## Endpoint reference

| Method   | Path                  | Description                                                |
| -------- | --------------------- | ---------------------------------------------------------- |
| `GET`    | `/v1/webhooks`        | List your registrations                                    |
| `GET`    | `/v1/webhooks/{type}` | Get one registration (`whale` or `arbitrage`)              |
| `POST`   | `/v1/webhooks/{type}` | Register a URL (**409** if one already exists — use `PUT`) |
| `PUT`    | `/v1/webhooks/{type}` | Update the callback URL                                    |
| `DELETE` | `/v1/webhooks/{type}` | Delete a registration                                      |

## Request

```
https://api.probsights.com/v1/webhooks/whale
```

### Body

<ParamField body="url" type="string" required>
  Public `http` or `https` callback URL. Private, loopback, and link-local hosts are
  rejected at registration time.
</ParamField>

## Response

Registration responses wrap data in the standard envelope (`success`, `data`, `message`).
The `data` object includes:

<ResponseField name="type" type="string">
  `whale` or `arbitrage`.
</ResponseField>

<ResponseField name="url" type="string">
  Your registered callback URL.
</ResponseField>

<ResponseField name="secret" type="string">
  Shared signing secret — store it to verify deliveries. Returned on every
  `GET` / `POST` / `PUT`, not only at creation.
</ResponseField>

<ResponseField name="enabled" type="boolean">
  Whether deliveries are active.
</ResponseField>

## What triggers a delivery

| Type        | Fires when                                                                         | Scope                                              |
| ----------- | ---------------------------------------------------------------------------------- | -------------------------------------------------- |
| `whale`     | A trade is ingested above the platform whale-notional threshold                    | Every customer with an enabled `whale` webhook     |
| `arbitrage` | The scanner finds an opportunity above `min_net_cents` outside the cooldown window | Every customer with an enabled `arbitrage` webhook |

Delivery is best-effort: slow or failing endpoints are logged and skipped — there is
no automatic retry queue.

## Delivery payload

```json theme={null}
{
  "type": "whale.entry",
  "data": {
    "exchange": "kalshi",
    "event_id": "…",
    "market_id": "…",
    "market_ticker": "KXBTC-25JAN01",
    "market_title": "…",
    "source_trade_id": "…",
    "executed_at": "2026-08-08T12:00:00Z",
    "taker_side": "buy",
    "price": 0.55,
    "size": 2000,
    "notional_usd": 1100.0
  }
}
```

`type` is `whale.entry` or `arbitrage.opportunity`. The `data` object follows the
field names used in [Whales](/api-reference/whales-overview) and
[Cross-venue arbitrage](/api-reference/arbitrage-current).

## Verifying deliveries

Every delivery includes:

| Header                    | Meaning                                                      |
| ------------------------- | ------------------------------------------------------------ |
| `Tiger-Webhook-Id`        | Unique per delivery                                          |
| `Tiger-Webhook-Timestamp` | Unix seconds at send time                                    |
| `Tiger-Webhook-Signature` | `v1,<base64 HMAC-SHA256>` over `{id}.{timestamp}.{raw body}` |

Recompute the HMAC with your stored `secret` over the exact signed string before
trusting the payload.

## Examples

### Register and manage

<CodeGroup>
  ```bash cURL (register whale) theme={null}
  curl -X POST -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url":"https://example.com/hooks/tiger-whale"}' \
    "https://api.probsights.com/v1/webhooks/whale"
  ```

  ```bash cURL (register arbitrage) theme={null}
  curl -X POST -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url":"https://example.com/hooks/tiger-arb"}' \
    "https://api.probsights.com/v1/webhooks/arbitrage"
  ```

  ```bash cURL (list) theme={null}
  curl -H "X-API-Key: YOUR_API_KEY" \
    "https://api.probsights.com/v1/webhooks"
  ```

  ```bash cURL (update) theme={null}
  curl -X PUT -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url":"https://example.com/hooks/tiger-whale-v2"}' \
    "https://api.probsights.com/v1/webhooks/whale"
  ```

  ```bash cURL (delete) theme={null}
  curl -X DELETE -H "X-API-Key: YOUR_API_KEY" \
    "https://api.probsights.com/v1/webhooks/whale"
  ```
</CodeGroup>

### Example registration response

```json theme={null}
{
  "success": true,
  "message": "Webhook registered",
  "data": {
    "id": "42",
    "type": "whale",
    "url": "https://example.com/hooks/tiger-whale",
    "secret": "whsec_…",
    "enabled": true,
    "created_at": "2026-08-08T12:00:00Z",
    "updated_at": "2026-08-08T12:00:00Z"
  }
}
```