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

# Webhooks

> Get notified when your users verify or remove a wallet, update their profile, receive the KOL badge or revoke access, about Trade Feed trades and copy trading instructions, and about platform users, competitions and callouts. Signed with Standard Webhooks.

Webhooks tell your backend when something changes for your users, so you do not have to poll. Set the webhook URL, choose the events and copy the signing secret in the dashboard on the instance's [Webhooks](https://docs.cabalspy.xyz/cabalspy-id/dashboard.md#webhooks) tab. There you can also send a test event, roll the signing secret, remove the webhook and see the recent deliveries.

Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com) specification, so you can verify them with its libraries for any language.

## Events

An event is sent to your instance when the user has signed in to it, your webhook subscribes to that event, and the user granted the scope the event needs. Events are only sent for users within your plan's user limit.

| Event | Scope | When |
| - | - | - |
| `wallet.verified` | `wallets` | The user verified a wallet with an on-chain payment. |
| `wallet.removed` | `wallets` | The user removed a verified wallet. |
| `profile.updated` | `profile` | The user signed in again and their X profile was refreshed. |
| `kol.granted` | `profile` | The user received the KOL badge. |
| `kol.rejected` | `profile` | A KOL badge application was declined; `data.note` says why. |
| `consent.revoked` | `openid` | The user no longer shares data with your app. |
| `thesis.created` | `thesis` | The user posted a [thesis](https://docs.cabalspy.xyz/cabalspy-id/theses.md), on your platform or any other. |
| `thesis.reply` | `thesis` | The user replied to a thesis. |
| `thesis.reaction` | `thesis` | The user added or removed a reaction. |
| `trade_feed.trade` | `trade_feed` | A trader in your users' [Trade Feeds](https://docs.cabalspy.xyz/cabalspy-id/trade-feed.md) traded. See [Trade Feed events](#trade-feed-events). |
| `trade_feed.thesis` | `trade_feed` | A trader in your users' Trade Feeds posted a thesis. |
| `copy_trade.instruction` | `trade_feed` | A copied trader traded: a ready-to-execute instruction for one user. See [Copy trading events](#copy-trading-events). |
| `platform_user.created` | `openid` | You created a [platform user](https://docs.cabalspy.xyz/cabalspy-id/white-label.md). See [White-Label events](#white-label-events). |
| `platform_user.merged` | `openid` | Your user proved an identity of their own CabalSpy ID; their `csid_id` changed. |
| `platform_user.self_managed` | `openid` | Your user signed in to their CabalSpy ID themselves and manages it now. |
| `platform_user.claimed` | `openid` | No longer sent (claim links are gone). |
| `platform_user.x_connected` | `openid` | A platform user connected X. |
| `platform_user.telegram_linked` | `openid` | A platform user linked Telegram. |
| `wallet.added` | `wallets` | A wallet was added to a platform user without payment verification. |
| `verification.expired` | `wallets` | A wallet verification you started for a platform user expired unpaid. |
| `competition.started` | `openid` | A [competition](https://docs.cabalspy.xyz/cabalspy-id/competitions.md) started. See [Competition events](#competition-events). |
| `competition.updated` | `openid` | A competition rule was changed. |
| `competition.standings` | `openid` | New standings were computed. |
| `competition.ended` | `openid` | A competition ended or was cancelled. |
| `callout.created` | `openid` | A user made a [callout](https://docs.cabalspy.xyz/cabalspy-id/callouts.md). See [Callout events](#callout-events). |
| `callout.milestone` | `openid` | A callout reached 2, 3, 5, 10, 20, 50 or 100x. |
| `callout.scored` | `openid` | A callout's first 24 hours were scored. |
| `callout.final` | `openid` | Tracking of a callout stopped. |
| `webhook.test` | none | You sent a test event from the dashboard. |

## Payload

Every delivery is a `POST` with a JSON body.

**id** `string`

Event id. The same on every retry, deduplicate on it.

**type** `string`

Event type, for example `wallet.verified`.

**created\_at** `string`

When the event happened (ISO 8601).

**sandbox** `boolean`

True for events of a sandbox instance.

**data** `object`

Event data. Always contains `sub`, the user's id, plus the fields below.

```json wallet.verified theme={null}
{
  "id": "6f1d2c9e-8b0a-4f7e-9a51-3c2d1e0f4b7a",
  "type": "wallet.verified",
  "created_at": "2026-10-12T14:21:07.402113+00:00",
  "sandbox": false,
  "data": {
    "sub": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
    "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
    "family": "solana",
    "chain": "solana",
    "tx": "5xr8..."
  }
}
```

```json wallet.removed theme={null}
{
  "id": "...",
  "type": "wallet.removed",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
    "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
    "family": "solana"
  }
}
```

```json profile.updated theme={null}
{
  "id": "...",
  "type": "profile.updated",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
    "preferred_username": "MazeCCC",
    "name": "Maze",
    "picture": "https://pbs.twimg.com/profile_images/.../photo.jpg",
    "followers": 48210,
    "following": 812,
    "posts": 15320
  }
}
```

```json kol.granted theme={null}
{
  "id": "...",
  "type": "kol.granted",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
    "preferred_username": "MazeCCC"
  }
}
```

```json consent.revoked theme={null}
{
  "id": "...",
  "type": "consent.revoked",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
    "reason": "user_removed_access"
  }
}
```

`thesis.created` carries the new thesis in `data.thesis`, the same object as in [List theses](https://docs.cabalspy.xyz/cabalspy-id/theses-list.md#response):

```json thesis.created theme={null}
{
  "id": "...",
  "type": "thesis.created",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
    "thesis": {
      "id": "8d1f5a2e-6c4b-4e0f-9a7d-1b2c3d4e5f60",
      "chain": "solana",
      "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
      "kind": "thesis",
      "body": "Strong community, still early.",
      "stance": "bull",
      "via": "Example Terminal",
      "...": "the full thesis object"
    }
  }
}
```

Thesis events go to the apps of the person who acted: the author of a thesis or reply, or the person who reacted. `thesis.reply` carries the reply in `data.reply`. `thesis.reaction` carries the post and the change:

```json thesis.reply theme={null}
{
  "id": "...",
  "type": "thesis.reply",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "5e2d8c41-7a9b-4c3e-b1f0-6d5e4c3b2a19",
    "reply": {
      "id": "2a9c7e10-4b3d-4f5e-8a6b-7c8d9e0f1a2b",
      "kind": "reply",
      "parent_id": "8d1f5a2e-6c4b-4e0f-9a7d-1b2c3d4e5f60",
      "body": "Nice call",
      "...": "the full reply object"
    }
  }
}
```

```json thesis.reaction theme={null}
{
  "id": "...",
  "type": "thesis.reaction",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "5e2d8c41-7a9b-4c3e-b1f0-6d5e4c3b2a19",
    "thesis_id": "8d1f5a2e-6c4b-4e0f-9a7d-1b2c3d4e5f60",
    "chain": "solana",
    "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
    "emoji": "🚀",
    "on": true,
    "reactions": { "like": 5, "🚀": 3 }
  }
}
```

`thesis.reaction` is only sent when the reaction actually changed, `on` is `true` for added and `false` for removed.

`consent.revoked` carries a `reason`: `user_removed_access` (the user removed your app), `blocked_by_platform` (you blocked the user in the dashboard) or `account_deleted` (the user deleted their CabalSpy ID). Delete the user's data you got from CabalSpy ID when you receive it. Their refresh tokens are already revoked.

## White-Label events

These events concern your [platform users](https://docs.cabalspy.xyz/cabalspy-id/white-label.md) and are only sent to the instance the user belongs to. Besides `data.sub`, every event about one of your platform users carries `data.external_id` (your own user id) and `data.csid_id`, so you can match it to your user without a lookup. Platform users hold every scope these events need.

```json platform_user.created theme={null}
{
  "id": "...",
  "type": "platform_user.created",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "external_id": "user_8412",
    "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "wallets": [
      { "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW", "family": "solana", "chains": ["solana"] }
    ]
  }
}
```

```json wallet.added theme={null}
{
  "id": "...",
  "type": "wallet.added",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "external_id": "user_8412",
    "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "address": "0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01",
    "family": "evm",
    "chains": ["base", "eth"],
    "source": "dynamic",
    "verified": false
  }
}
```

```json platform_user.merged theme={null}
{
  "id": "...",
  "type": "platform_user.merged",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
    "external_id": "user_8412",
    "csid_id": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
    "previous_csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "reason": "x_connected",
    "skipped_wallets": []
  }
}
```

```json platform_user.self_managed theme={null}
{
  "id": "...",
  "type": "platform_user.self_managed",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
    "external_id": "user_8412",
    "csid_id": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11"
  }
}
```

```json platform_user.x_connected theme={null}
{
  "id": "...",
  "type": "platform_user.x_connected",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "external_id": "user_8412",
    "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "x": { "id": "1440000000000000000", "username": "MazeCCC", "name": "Maze" }
  }
}
```

```json platform_user.telegram_linked theme={null}
{
  "id": "...",
  "type": "platform_user.telegram_linked",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "external_id": "user_8412",
    "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "telegram": { "username": "maze_trades" }
  }
}
```

```json verification.expired theme={null}
{
  "id": "...",
  "type": "verification.expired",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "sub": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "external_id": "user_8412",
    "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "verification_id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
    "chain": "solana",
    "family": "solana"
  }
}
```

`wallet.added` is sent once per wallet that was added or got new chains, with only the new chains. In `platform_user.merged`, `sub` is the person's own CabalSpy ID, which is the user's `csid_id` from now on, `previous_csid_id` the account your platform had created, and `reason` the proof: `x_connected`, `telegram_linked` or `wallet_verified`. `skipped_wallets` lists wallets you reported that did not fit the person's limit of 5 Solana and 5 EVM wallets. `verification.expired` is not sent for verifications you cancelled.

## Competition events

[Competition](https://docs.cabalspy.xyz/cabalspy-id/competitions.md) events concern your instance, not a single user.

```json competition.started theme={null}
{
  "id": "...",
  "type": "competition.started",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "competition_id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "name": "Weekend PnL Cup",
    "started_at": "2026-11-01T18:00:00Z",
    "ends_at": "2026-11-03T18:00:00Z",
    "participants": 214
  }
}
```

```json competition.updated theme={null}
{
  "id": "...",
  "type": "competition.updated",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "competition_id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "rules_version": 2,
    "during": "running",
    "changes": { "duration_hours": { "from": 48.0, "to": 72.0 } },
    "note": "Extended by one day after the outage."
  }
}
```

```json competition.standings theme={null}
{
  "id": "...",
  "type": "competition.standings",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "competition_id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "metric": "pnl_usd",
    "top": [
      { "rank": 1, "ranked": true, "external_id": "user_8412", "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718", "score": 3968.6, "...": "the standings entry" }
    ]
  }
}
```

```json competition.ended theme={null}
{
  "id": "...",
  "type": "competition.ended",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "competition_id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "name": "Weekend PnL Cup",
    "cancelled": false,
    "ended_at": "2026-11-03T18:00:00Z",
    "metric": "pnl_usd",
    "results": [
      { "rank": 1, "ranked": true, "external_id": "user_8412", "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718", "score": 5120.3, "...": "the standings entry" }
    ]
  }
}
```

`competition.standings` is sent after every computation, about every 5 minutes while a competition runs, with up to 20 ranked traders in `top`, as entries of [Standings](https://docs.cabalspy.xyz/cabalspy-id/competitions-standings.md#response). `competition.ended` carries up to 100 ranked traders in `results`; read the full results from Standings. A cancelled competition sends `competition.ended` with only `competition_id`, `"cancelled": true` and empty `results`.

## Callout events

[Callout](https://docs.cabalspy.xyz/cabalspy-id/callouts.md) events concern your instance, not a single user, so `data` has no `sub`. They are only offered in the event list of instances with callouts switched on. Callouts are switched on per instance on request, contact us at [contact@cabalspy.xyz](mailto:contact@cabalspy.xyz).

Each event carries the callout in `data.callout`, the same object as in [List callouts](https://docs.cabalspy.xyz/cabalspy-id/callouts-list.md#the-callout-object), with your `external_id` of the author in `data.callout.author`.

| Event | When | Extra |
| - | - | - |
| `callout.created` | A user made a callout. | |
| `callout.milestone` | The callout's peak multiple reached 2, 3, 5, 10, 20, 50 or 100x. Each milestone once per callout; when several are passed at once, only the highest. | `data.milestone_x` |
| `callout.scored` | About five minutes after the first 24 hours, when they were scored on candles. The callout keeps being tracked while its token is active. | `data.callout.first_day` |
| `callout.final` | Tracking stopped: the token's market cap stayed below \$10,000, or it had no price, for 24 hours in a row. The score no longer changes. | `data.callout.status` is `final`, `data.callout.tracking.stop_reason` is `inactive` or `no_price` |

Price updates and removals are not sent as webhooks; follow them on the [callouts stream](https://docs.cabalspy.xyz/cabalspy-id/callouts-stream.md).

```json callout.created theme={null}
{
  "id": "...",
  "type": "callout.created",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "callout": {
      "id": "5b0e7c3a-2d4f-4a6b-9c8d-1e2f3a4b5c6d",
      "chain": "solana",
      "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
      "token": { "name": "invisibull", "symbol": "invisibull", "logo": "https://..." },
      "author": { "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718", "external_id": "user_8412", "name": "Maze", "username": "MazeCCC", "avatar_url": "https://cdn.example.com/avatars/8412.png", "kol": false },
      "note": "Dev still holding, chart is coiling.",
      "called_at": "2026-11-01T18:02:11Z",
      "window_ends_at": "2026-11-02T18:02:11Z",
      "status": "tracking",
      "at_call": { "price_usd": 0.0000412, "market_cap_usd": 41200.0 },
      "now": { "price_usd": 0.0000412, "market_cap_usd": 41200.0, "x": 1.0, "at": "2026-11-01T18:02:11Z" },
      "peak": { "price_usd": 0.0000412, "market_cap_usd": 41200.0, "x": 1.0, "at": "2026-11-01T18:02:11Z" },
      "score_x": 1.0,
      "source": "mobula",
      "tracking": { "active": true, "phase": "first_day", "next_check_at": null, "below_10k_since": null, "daily_checks": 0, "stopped_at": null, "stop_reason": null }
    }
  }
}
```

```json callout.milestone theme={null}
{
  "id": "...",
  "type": "callout.milestone",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "callout": {
      "id": "5b0e7c3a-2d4f-4a6b-9c8d-1e2f3a4b5c6d",
      "chain": "solana",
      "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
      "status": "tracking",
      "peak": { "price_usd": 0.0000851, "market_cap_usd": 85100.0, "x": 2.0655, "at": "2026-11-01T18:47:00Z" },
      "score_x": 2.0655,
      "...": "the full callout object"
    },
    "milestone_x": 2
  }
}
```

```json callout.scored theme={null}
{
  "id": "...",
  "type": "callout.scored",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "callout": {
      "id": "5b0e7c3a-2d4f-4a6b-9c8d-1e2f3a4b5c6d",
      "status": "tracking",
      "score_x": 3.2346,
      "tracking": { "active": true, "phase": "extended", "next_check_at": "2026-11-03T18:02:11Z", "below_10k_since": null, "daily_checks": 1, "stopped_at": null, "stop_reason": null },
      "first_day": { "kind": "candles", "entry_price_usd": 0.0000405, "peak_x": 3.2346, "close_x": 1.8642, "minutes_to_peak": 98, "flags": [] },
      "...": "the full callout object"
    }
  }
}
```

```json callout.final theme={null}
{
  "id": "...",
  "type": "callout.final",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "callout": {
      "id": "5b0e7c3a-2d4f-4a6b-9c8d-1e2f3a4b5c6d",
      "status": "final",
      "score_x": 3.2346,
      "tracking": { "active": false, "phase": "stopped", "next_check_at": null, "below_10k_since": null, "daily_checks": 9, "stopped_at": "2026-11-10T07:15:00Z", "stop_reason": "inactive" },
      "...": "the full callout object"
    }
  }
}
```

## Trade Feed events

[Trade Feed](https://docs.cabalspy.xyz/cabalspy-id/trade-feed.md) events tell you about new trades and theses of the traders your users have in their Trade Feed, so you can send your own notifications. Each event is sent **once per trade or thesis** to each of your apps, not once per user.

`data` is the [trade item](https://docs.cabalspy.xyz/cabalspy-id/trade-feed-api.md#the-trade-item) or [thesis item](https://docs.cabalspy.xyz/cabalspy-id/trade-feed-api.md#the-thesis-item) as in the Trade Feed, plus:

| Field | Meaning |
| - | - |
| `recipients` | The `csid_id` of your users who have the trader in their Trade Feed and whose [filters](https://docs.cabalspy.xyz/cabalspy-id/trade-feed.md#alerts-and-filters) for that trader let this event through. Only users who granted `trade_feed` and are within your plan's user limit. |
| `recipients_external` | Your own user ids (`external_id`) of the recipients who are [platform users](https://docs.cabalspy.xyz/cabalspy-id/white-label.md). |

An event without recipients of yours is not sent. `data` has no `sub`. The same events are on the [Trade Feed stream](https://docs.cabalspy.xyz/cabalspy-id/trade-feed-api.md#live-stream).

```json trade_feed.trade theme={null}
{
  "id": "...",
  "type": "trade_feed.trade",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "id": "t3b1f0c9e8d7a6b5c4d3e2f1a0b9c8d7e",
    "type": "trade",
    "timestamp": "2026-11-01T18:40:05Z",
    "trader": { "csid_id": "7c2e9a14-6b3d-4f81-9e0a-5d4c3b2a1f09", "username": "MazeCCC", "name": "Maze", "image_url": "https://pbs.twimg.com/profile_images/1/maze_normal.jpg", "kol": true, "profile_url": "https://id.cabalspy.xyz/u/MazeCCC" },
    "trade": {
      "blockchain": "solana",
      "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
      "symbol": "CPT",
      "side": "sell",
      "label": "partial",
      "sold_percent": 50.0,
      "amount_native": 1.5,
      "currency": "SOL",
      "amount_usd": 225.0,
      "pnl_usd": 150.0,
      "wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
      "tx_signature": "2Bq7...",
      "...": "the full trade"
    },
    "links": { "token": "https://app.cabalspy.xyz/token/3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump", "terminal": "https://app.cabalspy.xyz/token/3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump", "profile": "https://id.cabalspy.xyz/u/MazeCCC" },
    "recipients": ["3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718"],
    "recipients_external": ["user_8412"]
  }
}
```

```json trade_feed.thesis theme={null}
{
  "id": "...",
  "type": "trade_feed.thesis",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "id": "h8a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "type": "thesis",
    "timestamp": "2026-11-01T18:21:44Z",
    "trader": { "csid_id": "7c2e9a14-6b3d-4f81-9e0a-5d4c3b2a1f09", "username": "MazeCCC", "...": "..." },
    "thesis": { "id": "8a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "blockchain": "solana", "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump", "stance": "bull", "body": "Dev still holding, chart is coiling.", "...": "..." },
    "links": { "...": "..." },
    "recipients": ["3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718"],
    "recipients_external": []
  }
}
```

## Copy trading events

`copy_trade.instruction` carries one ready-to-execute [copy instruction](https://docs.cabalspy.xyz/cabalspy-id/copy-trading.md#the-instruction): a trader one of your users copies has traded, and your app should execute the instruction with the user's wallet and [report the result](https://docs.cabalspy.xyz/cabalspy-id/copy-trading-status.md).

* One event **per user and trade**. Deduplicate on `data.id`, the instruction id, which is also the same on the [copy trading stream](https://docs.cabalspy.xyz/cabalspy-id/copy-trading-stream.md).
* Only sent to the apps of the instance that switched copying on for that user and trader. Other platforms of the same user get nothing, see [One platform at a time](https://docs.cabalspy.xyz/cabalspy-id/copy-trading.md#one-platform-at-a-time).
* Needs the scope `trade_feed`. Platform users always have it.

`data` is the instruction object plus `external_id`, your own id of the user when they are a platform user, otherwise null. `data` has no `sub`; the user is `data.csid_id`.

Instructions are meant to be executed within 120 seconds (`data.expires_at`). Answer the webhook right away and execute afterwards: a retried delivery may arrive after the instruction expired.

```json copy_trade.instruction theme={null}
{
  "id": "...",
  "type": "copy_trade.instruction",
  "created_at": "...",
  "sandbox": false,
  "data": {
    "id": "9d4b2f6e-1c3a-5e7f-8a9b-0c1d2e3f4a5b",
    "type": "copy_instruction",
    "status": "pending",
    "created_at": "2026-11-01T18:02:11Z",
    "expires_at": "2026-11-01T18:04:11Z",
    "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "external_id": "user_8412",
    "trader": { "csid_id": "7c2e9a14-6b3d-4f81-9e0a-5d4c3b2a1f09", "username": "MazeCCC", "name": "Maze", "image_url": "https://pbs.twimg.com/profile_images/1/maze_normal.jpg", "kol": true, "profile_url": "https://id.cabalspy.xyz/u/MazeCCC" },
    "action": {
      "blockchain": "solana",
      "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
      "symbol": "CPT",
      "name": "Copycat",
      "logo": "https://...",
      "side": "buy",
      "amount_usd": 20.0,
      "amount_native": 0.133333333,
      "currency": "SOL",
      "sell_percent": null,
      "price_usd": 0.15,
      "max_price_usd": 0.1545,
      "min_price_usd": null,
      "slippage_bps": 300
    },
    "source_trade": { "side": "buy", "label": "new", "amount_native": 1.0, "amount_usd": 150.0, "price_usd": 0.15, "...": "the trader's trade" },
    "settings": { "enabled": true, "mode": "fixed_usd", "amount_usd": 25.0, "percent": 100.0, "max_usd": 20.0, "sides": "both", "slippage_bps": 300, "updated_at": "2026-11-01T17:58:40Z" },
    "links": { "token": "https://app.cabalspy.xyz/token/3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump", "terminal": "https://app.cabalspy.xyz/token/3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump", "profile": "https://id.cabalspy.xyz/u/MazeCCC" }
  }
}
```

## Headers

| Header | Value |
| - | - |
| `webhook-id` | The event id, the same on every retry. |
| `webhook-timestamp` | Unix time in seconds when the delivery was sent. |
| `webhook-signature` | `v1,<base64 signature>`. During a secret roll, one signature per active secret, separated by spaces. |
| `CSID-Event-Type` | The event type. |
| `Content-Type` | `application/json` |
| `User-Agent` | `CabalSpy-ID-Webhooks/1` |

## Verify the signature

The signature is an HMAC-SHA256 over `<webhook-id>.<webhook-timestamp>.<raw body>`, keyed with the base64-decoded part of your secret after `whsec_`. Always verify against the raw request body, and reject deliveries whose timestamp is more than 5 minutes off.

```javascript Node.js theme={null}
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.CSID_WEBHOOK_SECRET; // whsec_...
const app = express();

function verify(rawBody, headers) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  const sigs = (headers["webhook-signature"] || "").split(" ");
  if (!id || !ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const key = Buffer.from(SECRET.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key)
    .update(`${id}.${ts}.`).update(rawBody).digest();

  return sigs.some((s) => {
    const [version, value] = s.split(",");
    if (version !== "v1" || !value) return false;
    const given = Buffer.from(value, "base64");
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

app.post("/webhooks/csid", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.body, req.headers)) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  // dedupe on event.id, then handle event.type
  res.sendStatus(204);
});
```

```python Python theme={null}
import base64, hashlib, hmac, json, os, time
from flask import Flask, request

SECRET = os.environ["CSID_WEBHOOK_SECRET"]  # whsec_...
app = Flask(__name__)

def verify(body: bytes, headers) -> bool:
    msg_id = headers.get("webhook-id", "")
    ts = headers.get("webhook-timestamp", "")
    if not msg_id or not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    key = base64.b64decode(SECRET.removeprefix("whsec_"))
    expected = hmac.new(key, f"{msg_id}.{ts}.".encode() + body, hashlib.sha256).digest()
    for sig in headers.get("webhook-signature", "").split():
        version, _, value = sig.partition(",")
        if version == "v1" and hmac.compare_digest(base64.b64decode(value), expected):
            return True
    return False

@app.post("/webhooks/csid")
def csid_webhook():
    if not verify(request.get_data(), request.headers):
        return "", 400
    event = json.loads(request.get_data())
    # dedupe on event["id"], then handle event["type"]
    return "", 204
```

```python Standard Webhooks library theme={null}
from standardwebhooks.webhooks import Webhook

wh = Webhook(os.environ["CSID_WEBHOOK_SECRET"])  # whsec_...
event = wh.verify(request.get_data(), dict(request.headers))  # raises on a bad signature
```

## Delivery and retries

Webhook URLs must use `https` and resolve to a public address. Answer with any `2xx` status within 10 seconds, ideally right away, and do the work afterwards. Redirects are not followed.

Any other answer, a timeout or a connection error is retried after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 3 hours, 6 hours, 12 hours and 24 hours, about two days in total. After the last attempt the delivery is marked failed. The dashboard shows the recent deliveries of your instance with their status.

Deliveries can arrive more than once and out of order. Deduplicate on `webhook-id` and, when order matters, compare `created_at`.

## Rolling the secret

When you roll the secret in the dashboard, the old secret stays valid for a while. During that time every delivery carries one signature per active secret in `webhook-signature`, separated by spaces, so both your old and new deployment accept it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.