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.Payload
Every delivery is aPOST with a JSON body.
thesis.created carries the new thesis in data.thesis, the same object as in List theses:
thesis.created
thesis.reply carries the reply in data.reply. thesis.reaction carries the post and the change:
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 and are only sent to the instance the user belongs to. Besidesdata.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.
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 events concern your instance, not a single user.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. 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 events concern your instance, not a single user, sodata 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.
Each event carries the callout in data.callout, the same object as in List callouts, with your external_id of the author in data.callout.author.
Price updates and removals are not sent as webhooks; follow them on the callouts stream.
Trade Feed events
Trade Feed 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 or thesis item as in the Trade Feed, plus:
An event without recipients of yours is not sent.
data has no sub. The same events are on the Trade Feed stream.
Copy trading events
copy_trade.instruction carries one ready-to-execute copy 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.
- One event per user and trade. Deduplicate on
data.id, the instruction id, which is also the same on the copy trading stream. - 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.
- 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.
copy_trade.instruction
Headers
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.
Delivery and retries
Webhook URLs must usehttps 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 inwebhook-signature, separated by spaces, so both your old and new deployment accept it.
