Build on the click-fraud platform.

Quickstart#

1. 1Open Settings → API & Webhooks in your dashboard.
2. 2Create a token, pick the abilities you need, and copy it once — it will not be shown again.
3. 3Send requests with Authorization: Bearer YOUR_TOKEN.

curl https://api.myclickshield.com/api/v1/sites \
  -H 'Authorization: Bearer YOUR_TOKEN'

Authentication#

Every request must include a bearer token in the Authorization header.

Authorization: Bearer mcs_live_...

Tokens are scoped to one account, can be granted a subset of abilities, and can be set to expire after 30, 90, 180, 365 or 730 days. Lost tokens cannot be recovered — revoke and create a new one. Maximum 20 tokens per account.

Token abilities#

Each token carries a set of abilities. A request fails with 403 Forbidden if the token doesn't carry the ability the endpoint requires.

Rate limits#

60 requests per minute per token. The standard rate-limit headers are returned on every response; over-limit requests get a 429 Too Many Requests.

• X-RateLimit-Limit

  Window cap

• X-RateLimit-Remaining

  Requests left

• Retry-After

  Seconds to wait

Errors#

All errors return a JSON body of the shape { "message": "..." }.

Overview#

Subscribe to events and receive a signed POST whenever they happen — no polling required. Configure endpoints under Settings → API & Webhooks. You can have up to 10 endpoints per account.

Each delivery is a JSON POST with these headers:

• X-MyClickShield-EventEvent name (e.g. ip.blocked)
• X-MyClickShield-TimestampUnix timestamp in seconds
• X-MyClickShield-SignatureHMAC-SHA256 hex digest
• X-MyClickShield-DeliveryUnique delivery ID for idempotency

POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-MyClickShield-Event: ip.blocked
X-MyClickShield-Timestamp: 1746367200
X-MyClickShield-Signature: 9f7c4...
X-MyClickShield-Delivery: 5821

{
  "event": "ip.blocked",
  "data": {
    "site_id": 17,
    "site_domain": "acme-coffee.com",
    "ip_address": "203.0.113.42",
    "reason": "Auto-blocked due to high fraud score",
    "fraud_score": 88,
    "source": "auto"
  },
  "sent_at": "2026-05-04T12:00:00+00:00"
}

Verifying signatures#

Compute HMAC_SHA256(secret, timestamp + "." + raw_body) and compare in constant time. Reject if the signature mismatches or the timestamp is more than 5 minutes old (replay protection).

import crypto from 'crypto'

app.post('/webhooks/myclickshield', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.headers['x-myclickshield-timestamp']
  const sig = req.headers['x-myclickshield-signature']
  const body = req.body.toString()

  const expected = crypto
    .createHmac('sha256', process.env.MCS_WEBHOOK_SECRET)
    .update(ts + '.' + body)
    .digest('hex')

  if (
    sig.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig)) ||
    Math.abs(Date.now() / 1000 - Number(ts)) > 300
  ) {
    return res.status(400).send('invalid signature')
  }

  const payload = JSON.parse(body)
  // ... handle payload.event ...
  res.sendStatus(200)
})

Event catalog#

Retries & auto-disable#

Non-2xx responses and transport errors trigger up to 5 attempts with exponential back-off:

1. immediate→
2. 30s→
3. 2m→
4. 5m→
5. 30m

After 20 consecutive failures the endpoint is auto-disabled — re-enable it from the dashboard once you've fixed your receiver. A 2xx reply confirms delivery; we don't expect any specific body.