Event types
| Event type | Status | Fires when |
|---|---|---|
whale_trades_inserted | Live | One or more new whale trades are ingested. The payload carries the count. |
live_sports_updated | Reserved | Accepted on subscribe, not yet emitted. |
whale_trader_synced | Reserved | Accepted on subscribe, not yet emitted. |
large_positions_updated | Reserved | Accepted on subscribe, not yet emitted. |
whale_trades_inserted is the only event delivered. You can subscribe to the reserved types now; they will begin delivering when emission ships, with no change to your verification code.
A whale_trades_inserted delivery body:
GET /api/v1/whale-trades (newest first) when you receive it.
Set up an endpoint
1. Create it
https and publicly routable. Localhost and private IP literals are rejected. You can register up to 10 endpoints.
The create response includes two values you only see once:
signing_secret now. It is shown only on create and on rotate-secret, never on a later read. The webhook id is an integer.
2. Verify it
A new endpoint starts inpending_verification and receives nothing until you verify it. Prove you control the secret by sending the verification token back within 24 hours:
active and deliveries begin. Verification does not send a test delivery; it activates the endpoint by matching the token from create.
Delivery format
Every delivery is an HTTP POST with a JSON body and these headers:| Header | Value |
|---|---|
x-0xinsider-signature | v1=<hex>: the HMAC signature. |
x-0xinsider-timestamp | Unix seconds when the delivery was signed. |
x-0xinsider-event-id | Stable per-event id. Dedupe on this. |
x-0xinsider-event-type | The event type. |
x-0xinsider-delivery-id | Id of this delivery attempt’s row. |
x-0xinsider-delivery-attempt | Attempt counter, starting at 1. |
Verify the signature
The signature is computed over the timestamp and the raw request body, joined by a literal.:
- Use the raw request body bytes, exactly as received. Do not parse and re-serialize the JSON first; whitespace and key order would change and the HMAC would not match.
- Use the
signing_secretstring as the HMAC key, the fullwhsec_...value.
x-0xinsider-timestamp is more than 5 minutes from your clock (a replay guard you enforce on your side).
Retries and idempotency
Respond with any2xx to mark a delivery successful. Anything else, or a timeout, counts as a failure.
- Timeout: respond within 15 seconds. ACK fast, then do slow work asynchronously.
- Retries: a failed delivery is retried up to 8 attempts, roughly a minute apart. After the last attempt it is moved to a dead-letter state and not retried.
- Idempotency: the same logical event always carries the same
x-0xinsider-event-id. A retried delivery reuses itsx-0xinsider-delivery-idand incrementsx-0xinsider-delivery-attempt. Dedupe your processing onx-0xinsider-event-idso a redelivery does not double-handle.
Manage and rotate
- Update the URL, events, or enabled flag. Changing the URL drops the endpoint back to
pending_verificationand issues a fresh verification token. - Rotate the secret if it leaks. The old secret stops working the moment the call returns, so deploy the new one to your verifier first.
- Disable to stop deliveries without losing the registration, or set
enabled: falsevia update.
Don’t have a public endpoint yet?
Poll instead.GET /api/v1/whale-trades is the live feed, GET /api/v1/events/feed/since is a durable cursor-based replay of the same events, and GET /api/v1/stream is a real-time SSE stream. The alert bot recipe shows both the webhook and the polling path.