Webhooks Documentation

1. Create a Webhook Endpoint

First, create an HTTP endpoint on your server that can receive POST requests:

// Node.js/Express example
app.post('/webhooks/license-validator', (req, res) => {
  const event = req.body;

  console.log('Received event:', event.event);
  console.log('Data:', event.data);

  // Process the event
  // ... your business logic here

  // Return 200 OK to acknowledge receipt
  res.status(200).send('OK');
});

2. Register Your Webhook

1. 1Navigate to the Webhooks page in your dashboard
2. 2Click "Create Webhook"
3. 3Enter your webhook URL (must be HTTPS)
4. 4Select which events you want to receive
5. 5Save - you'll receive a webhook secret (save it securely!)

3. Test Your Webhook

Use the "Test" button in the dashboard to send a test event and verify your endpoint is working.

Node.js / Express

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');

  // Use timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body.toString('utf8');
  const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const event = JSON.parse(payload);
  res.status(200).send('OK');
});

Python / Flask

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected_signature, signature)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature')
    payload = request.get_data(as_text=True)

    if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
        abort(401)

    event = request.get_json()
    return 'OK', 200

PHP

<?php
function verifyWebhookSignature($payload, $signature, $secret) {
    $expectedSignature = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expectedSignature, $signature);
}

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (!verifyWebhookSignature($payload, $signature, $webhookSecret)) {
    http_response_code(401);
    die('Invalid signature');
}

http_response_code(200);
echo 'OK';
?>

Using the Dashboard

1. 1. Go to the Webhooks page
2. 2. Click the "Test" button next to your webhook
3. 3. A test event will be sent immediately
4. 4. Check the response and your server logs

Local Testing with ngrok

To test webhooks on your local development machine:

# 1. Start your local server
node server.js
# Server running on http://localhost:3000

# 2. Start ngrok tunnel
ngrok http 3000

# 3. Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
# 4. Create webhook with: https://abc123.ngrok.io/webhook
# 5. View requests at: http://127.0.0.1:4040

Send Slack Notifications

const { WebClient } = require('@slack/web-api');
const slack = new WebClient(process.env.SLACK_BOT_TOKEN);

async function handleLicenseActivated(data) {
  await slack.chat.postMessage({
    channel: '#license-alerts',
    text: `🎉 New license activation!`,
    blocks: [{
      type: 'section',
      text: {
        type: 'mrkdwn',
        text: `*New Device Activated*\n\n*License:* ${data.licenseName}\n*Customer:* ${data.customerName}\n*Device:* ${data.deviceName}`
      }
    }]
  });
}

Send Email with SendGrid

const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);

async function handleLicenseExpired(data) {
  await sgMail.send({
    to: data.customerEmail,
    from: 'noreply@yourdomain.com',
    subject: 'License Expiration Notice',
    html: `<p>Your license <strong>${data.licenseName}</strong> has expired.</p>`
  });
}

Log to Database

const { Pool } = require('pg');
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

async function handleLicenseValidated(data) {
  await pool.query(
    `INSERT INTO license_events (event_type, license_id, device_fingerprint, timestamp)
     VALUES ($1, $2, $3, $4)`,
    ['validated', data.licenseId, data.fingerprint, new Date()]
  );
}

Webhook Not Firing

• Check webhook is enabled (Status: Active)
• Verify event subscriptions are correct
• Ensure you have Professional or Enterprise plan
• Test the webhook using the Test button
• Review webhook logs for delivery attempts

Signature Verification Failing

• Ensure you're using the correct webhook secret
• Use raw JSON body (not parsed object) for verification
• Verify you're using HMAC-SHA256 algorithm
• Use timing-safe comparison functions
• Check for UTF-8 encoding issues

Webhook Timing Out

• Respond with 200 OK within 10 seconds
• Process webhook data asynchronously
• Avoid slow database queries before responding
• Don't wait for external API calls
• Use background jobs for long operations

Create Webhook

Authentication: Required (Professional/Enterprise only)

// Request
{
  "url": "https://yourdomain.com/webhook",
  "events": ["license.validated", "license.activated"],
  "isActive": true
}

// Response (201)
{
  "id": "webhook_abc123",
  "secret": "whsec_def456...", // Only shown once!
  "url": "https://yourdomain.com/webhook",
  "events": ["license.validated", "license.activated"],
  "isActive": true
}

Test Webhook

// Request
{
  "webhookId": "webhook_abc123"
}

// Response (200)
{
  "success": true,
  "deliveryId": "delivery_test_xyz789",
  "statusCode": 200,
  "responseTime": 123
}