Webhooks

Prerequisites

• A Premium CardMind subscription — free tier keys receive 403 PREMIUM_REQUIRED
• A publicly reachable HTTPS endpoint on your server to receive POST requests
• The ability to verify HMAC-SHA256 signatures (recommended)

Registering a Webhook

Send a POST to /api/webhooks with the destination URL and the event types you want to subscribe to.

Request body

Example request

curl -X POST "https://api.cardmind.app/api/webhooks" \
  -H "Authorization: Bearer cm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/cardmind",
    "events": ["signal.buy", "signal.sell", "price.spike"]
  }'

Example response

{
  "data": {
    "id": "wh_01hwqbc34xem9e4b3kga70x7v2",
    "url": "https://your-server.com/webhooks/cardmind",
    "events": ["signal.buy", "signal.sell", "price.spike"],
    "created_at": "2026-04-17T12:00:00Z",
    "signing_secret": "whsec_aB3cD4eF5gH6iJ7kL8mN9oP0"
  },
  "error": null
}

The signing_secret is shown only once at registration time. Store it securely — you will need it to verify incoming webhook signatures.

Event Types

Webhook Payload

CardMind delivers a POST request to your endpoint with a JSON body. Every payload shares the same top-level shape regardless of event type.

{
  "event": "signal.buy",
  "data": {
    "card_id": "e3285e6b-3e79-4d7c-bf96-d920f973b122",
    "card_name": "Lightning Bolt",
    "signal_type": "BUY",
    "reason": "34% price increase over 7 days with rising tournament play",
    "price_at_signal": "1.49"
  },
  "timestamp": "2026-04-17T18:30:00Z",
  "signature": "sha256=a1b2c3d4e5f6..."
}

Signature Verification

Every webhook delivery includes a signature field computed as HMAC-SHA256(raw_body, signing_secret). Always verify the signature before processing a webhook to prevent spoofed requests.

Python verification example

import hmac
import hashlib

def verify_webhook(raw_body: bytes, signature: str, signing_secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        signing_secret.encode(),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

JavaScript / Node.js verification example

import crypto from 'crypto'

function verifyWebhook(rawBody, signature, signingSecret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', signingSecret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  )
}

Retry Policy

CardMind retries failed webhook deliveries with exponential backoff. A delivery is considered successful if your endpoint returns any 2xx HTTP status code within 10 seconds.

After 5 failed attempts the webhook registration is marked inactive. You can reactivate it at any time via PATCH /api/webhooks/:id.