Webhooks

Register a webhook subscription

Min tier: free. Registers an HTTPS callback that the dispatcher POSTs on every new whale/insider signal matching the filters, signed with an X-CrowdIntel-Signature HMAC header and retried on failure.

The secret is returned once, in this response only — GET /v1/webhooks always reports secret: null. There is no PATCH: changing a subscription means delete + recreate, which rotates the secret.

Validation (all rejected with 400 bad_request):

  • callback_url must be an absolute https: URL with a publicly routable host — localhost, *.local, *.internal, 0.0.0.0 and private/loopback/link-local IP literals are refused (SSRF guard). The host is re-resolved and re-checked at delivery time, so a DNS-rebinding target registers but never fires.
  • Filter fields are top-level, not nested.
  • Exceeding the cap of 10 subscriptions per account returns 400 (not 409/429).

Unrecognised body fields are ignored.

post/v1/webhooks

Request

  • Base URL: https://crowdintel.xyz/api
  • URL: https://crowdintel.xyz/api/v1/webhooks
  • Auth: HTTP bearer

Request body

callback_urlstring uri required

Absolute https URL with a publicly routable host.

min_scorenumber

Only deliver signals scoring at or above this. Omit for no floor.

score_type'whale' | 'insider'

Omit to receive both kinds.

categorystring

Market category, compared case-insensitively. Omit for any market.

Example request

{
  "callback_url": "https://example.com/hooks/crowdintel"
}

Response

Subscription created. secret is shown here and never again.

idinteger required
callback_urlstring uri required
activeboolean required
secretstring required

HMAC signing key (whsec_…) for the X-CrowdIntel-Signature header. Returned ONCE — store it now.

created_atstring date-time required

Example response

{
  "secret": "whsec_..."
}

Changes

No recorded changes to this operation across all 1 revision of this API.