Webhooks & Integrations

Receive real-time notifications when events occur in CloakRadar. Integrate with Slack, Telegram, Discord, or any custom endpoint.

Overview

Webhooks allow CloakRadar to push real-time data to your systems when specific events occur. Instead of polling our API, you receive instant notifications.

Use Cases

• Get notified when conversions happen
• Alert your team when fraud is detected
• Sync data with your CRM or tracking system
• Trigger automated workflows

Setting Up Webhooks

Create a Webhook

Webhook Events

Subscribe to the events you want to receive:

Payload Format

Standard Webhook Payload

All webhooks send a JSON POST request:

{
  "event": "conversion.new",
  "timestamp": "2024-01-15T14:30:00Z",
  "webhook_id": "wh_abc123",
  "data": {
    "click_id": "clk_xyz789",
    "campaign": {
      "id": 1,
      "name": "Facebook - Weight Loss"
    },
    "conversion": {
      "id": "conv_def456",
      "payout": 45.00,
      "currency": "USD",
      "transaction_id": "txn_12345"
    },
    "visitor": {
      "country": "US",
      "device": "mobile",
      "os": "iOS"
    }
  }
}

Event-Specific Payloads

conversion.new

{
  "event": "conversion.new",
  "data": {
    "click_id": "clk_xyz789",
    "campaign_name": "Facebook - Weight Loss",
    "offer_name": "Keto Diet",
    "payout": 45.00,
    "country": "US",
    "device": "mobile"
  }
}

fraud.detected

{
  "event": "fraud.detected",
  "data": {
    "click_id": "clk_abc123",
    "campaign_name": "Google - Finance",
    "fraud_type": "click_farm",
    "fraud_score": 85,
    "indicators": ["consistent_timing", "same_ip_pattern"],
    "ip": "192.168.x.x",
    "estimated_loss": 0.75
  }
}

bot.detected

{
  "event": "bot.detected",
  "data": {
    "click_id": "clk_def456",
    "campaign_name": "TikTok - Ecom",
    "bot_type": "selenium",
    "confidence": 98,
    "user_agent": "Mozilla/5.0...",
    "indicators": ["webdriver_present", "missing_plugins"]
  }
}

Slack Integration

Setup

1. Create a Slack Incoming Webhook
2. Copy the webhook URL
3. In CloakRadar, create a new webhook with type Slack
4. Paste the Slack webhook URL
5. Select your events and save

Message Format

Slack messages are formatted with rich attachments:

🎉 New Conversion!
Campaign: Facebook - Weight Loss
Offer: Keto Diet
Payout: $45.00
Country: United States
Device: Mobile (iOS)

Telegram Integration

Setup

1. Create a bot using @BotFather
2. Get your bot token
3. Get your chat ID (message @userinfobot)
4. In CloakRadar, create a webhook with type Telegram
5. Enter: https://api.telegram.org/bot{TOKEN}/sendMessage?chat_id={CHAT_ID}

Message Format

Messages are sent with HTML formatting:

🎉 New Conversion!

📊 Campaign: Facebook - Weight Loss
💰 Payout: $45.00
🌍 Country: United States
📱 Device: Mobile

Discord Integration

Setup

1. In your Discord server, go to Server Settings > Integrations
2. Click Webhooks > New Webhook
3. Copy the webhook URL
4. In CloakRadar, create a webhook with type Discord
5. Paste the Discord webhook URL

Message Format

Discord webhooks use rich embeds with colors:

• Green - Conversions
• Red - Fraud alerts
• Orange - Warnings
• Blue - Info

Security & Verification

Signature Verification

All webhooks include a signature header for verification:

X-CloakRadar-Signature: sha256=abc123...

Verifying the Signature (PHP)

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_CLOAKRADAR_SIGNATURE'];
$secret = 'your_webhook_secret';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (hash_equals($expected, $signature)) {
    // Valid webhook
    $data = json_decode($payload, true);
    // Process the event...
} else {
    // Invalid signature
    http_response_code(401);
    exit('Invalid signature');
}

Verifying the Signature (Node.js)

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
    const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');

    return crypto.timingSafeEqual(
        Buffer.from(expected),
        Buffer.from(signature)
    );
}

Best Practices

• Always verify the signature before processing
• Use HTTPS endpoints only
• Respond with 200 OK quickly (process async if needed)
• Handle duplicate events (use event IDs for deduplication)

Troubleshooting

Webhook Not Receiving Events

1. Check that the webhook is Active
2. Verify the URL is correct and accessible
3. Check that you've subscribed to the right events
4. View Webhook Logs for errors

Webhook Returning Errors

Common HTTP errors and solutions:

Retry Policy

Failed webhooks are retried up to 3 times:

• 1st retry: After 1 minute
• 2nd retry: After 5 minutes
• 3rd retry: After 30 minutes

After 3 failures, the webhook is marked as failed and disabled. You'll receive an email notification.

Viewing Webhook Logs

1. Go to Settings > Webhooks
2. Click on a webhook
3. Click View Logs

Logs show:

• Event type and timestamp
• Request payload sent
• Response status code
• Response body (if error)
• Retry attempts

Need more help? Check the FAQ & Troubleshooting section.