Webhook Integration Guide

{
  "id": "whd_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "event": "Payment completed",
  "timestamp": "2025-01-22T14:30:00.000Z",
  "version": "1.0",
  "tenant": {
    "id": 123,
    "name": "Artist Label Inc.",
    "domain": "artist-label.royalti.io"
  },
  "source": {
    "service": "royalti-api",
    "environment": "production",
    "traceId": "req_abc123xyz"
  },
  "data": {
    "event": {
      "id": "evt_456def",
      "type": "Payment completed",
      "category": "FINANCIAL",
      "timestamp": "2025-01-22T14:30:00.000Z",
      "importance": "critical"
    },
    "actor": {
      "id": "usr_789ghi",
      "type": "user",
      "name": "John Admin",
      "email": "john@artist-label.com"
    },
    "resource": {
      "type": "payment",
      "id": "pay_123abc",
      "url": "/api/v1/payment/pay_123abc",
      "displayName": "Payment to Artist Name"
    },
    "attributes": {
      "amount": 1500.00,
      "currency": "USD",
      "recipientId": "usr_456def",
      "recipientName": "Artist Name",
      "method": "stripe",
      "transactionId": "txn_stripe_789xyz",
      "status": "completed"
    },
    "previous": {
      "status": "processing",
      "updatedAt": "2025-01-22T14:25:00.000Z"
    }
  },
  "delivery": {
    "attempt": 1,
    "maxAttempts": 3,
    "nextRetryAt": null
  }
}

# Set webhook URL
curl -X PUT https://api.royalti.io/tenant/settings/webhook-config.url \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"value": "https://your-domain.com/webhooks/royalti"}'
# Enable webhooks
curl -X PUT https://api.royalti.io/tenant/settings/webhook-config.isActive \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"value": true}'
# Subscribe to specific events (JSON array)
curl -X PUT https://api.royalti.io/tenant/settings/webhook-config.enabledEvents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"value": ["Payment completed", "Track created", "User created", "Royalty File processed"]}'
# Enable signature validation (recommended for production)
curl -X PUT https://api.royalti.io/tenant/settings/webhook-config.enableSignatureValidation \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"value": true}'
# Set secret token (use a strong, random value — 32+ chars recommended)
curl -X PUT https://api.royalti.io/tenant/settings/webhook-config.secretToken \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"value": "your-secure-random-secret-token-min-32-chars"}'
# Configure retry attempts
curl -X PUT https://api.royalti.io/tenant/settings/webhook-config.retryAttempts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"value": 5}'
# Set timeout (45 seconds)
curl -X PUT https://api.royalti.io/tenant/settings/webhook-config.timeoutMs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"value": 45000}'

curl -X GET "https://api.royalti.io/webhook-deliveries?page=1&size=20&status=failed" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "status": "success",
  "message": "Webhook deliveries retrieved successfully",
  "data": {
    "webhookDeliveries": [
      {
        "id": "whd_123",
        "eventType": "Payment completed",
        "requestUrl": "https://your-domain.com/webhooks/royalti",
        "deliveryStatus": "failed",
        "responseStatus": 500,
        "responseTimeMs": 5234,
        "attemptNumber": 3,
        "finalAttempt": true,
        "errorCode": "SERVER_ERROR",
        "errorMessage": "Internal server error",
        "createdAt": "2025-01-22T14:30:00Z"
      }
    ],
    "totalItems": 150,
    "totalPages": 8,
    "currentPage": 1
  }
}

curl -X GET "https://api.royalti.io/webhook-deliveries/summary" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "status": "success",
  "data": {
    "summary": {
      "totalDeliveries": 1542,
      "successRate": "95.8%",
      "dateRange": {
        "start": "2025-01-01T00:00:00Z",
        "end": "2025-01-22T23:59:59Z"
      }
    },
    "statusBreakdown": {
      "success": 1477,
      "failed": 45,
      "timeout": 15,
      "pending": 5
    },
    "topEventTypes": [
      {"eventType": "Payment completed", "count": 523},
      {"eventType": "Track created", "count": 412},
      {"eventType": "User created", "count": 287}
    ],
    "recentFailures": [
      {
        "id": "whd_123",
        "eventType": "Payment completed",
        "errorCode": "TIMEOUT",
        "createdAt": "2025-01-22T14:30:00Z"
      }
    ]
  }
}

curl -X GET "https://api.royalti.io/webhook-deliveries/stats?timeframe=7d" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -X POST "https://api.royalti.io/webhook-deliveries/whd_123/retry" \
  -H "Authorization: Bearer YOUR_TOKEN"

Content-Type: application/json
X-Royalti-Delivery: whd_f47ac10b-58cc-4372-a567-0e02b2c3d479
X-Royalti-Event: Payment completed
X-Royalti-Timestamp: 1706019000
X-Royalti-Tenant: 123
X-Royalti-Attempt: 1
X-Royalti-Version: 1.0
X-Royalti-Signature: sha256=5d41402abc4b2a76b9719d911017c592

curl -X POST "https://api.royalti.io/webhook-deliveries/whd_123/retry" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "id": "whd_test_123",
  "event": "Payment completed",
  "timestamp": "2025-01-22T14:30:00.000Z",
  "version": "1.0",
  "tenant": {"id": 123, "name": "Test Workspace"},
  "source": {"service": "royalti-api", "environment": "production"},
  "data": {
    "event": {
      "id": "evt_456",
      "type": "Payment completed",
      "category": "FINANCIAL",
      "importance": "critical"
    },
    "actor": {
      "id": "usr_789",
      "type": "user",
      "name": "Test User"
    },
    "resource": {
      "type": "payment",
      "id": "pay_abc",
      "displayName": "Payment to Test Artist"
    },
    "attributes": {
      "amount": 1000.00,
      "currency": "USD",
      "recipientId": "usr_def",
      "method": "stripe",
      "status": "completed"
    }
  },
  "delivery": {"attempt": 1, "maxAttempts": 3}
}

{
  "id": "whd_test_456",
  "event": "Track created",
  "timestamp": "2025-01-22T15:00:00.000Z",
  "version": "1.0",
  "tenant": {"id": 123, "name": "Test Workspace"},
  "source": {"service": "royalti-api", "environment": "production"},
  "data": {
    "event": {
      "id": "evt_789",
      "type": "Track created",
      "category": "CATALOG",
      "importance": "medium"
    },
    "actor": {
      "id": "usr_123",
      "type": "user",
      "name": "Test User"
    },
    "resource": {
      "type": "asset",
      "id": "ast_xyz",
      "displayName": "New Song Title",
      "url": "/api/v1/asset/ast_xyz"
    },
    "attributes": {
      "title": "New Song Title",
      "artists": ["Artist Name"],
      "mediaType": "audio",
      "duration": 210,
      "isrc": "USRC12345678",
      "releaseDate": "2025-02-01"
    }
  },
  "delivery": {"attempt": 1, "maxAttempts": 3}
}

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "tenant": 123
}

const crypto = require('crypto');
const axios = require('axios');
async function notifyRoyaltiFileProcessed(fileId, tenantId) {
  const payload = {
    id: fileId,
    tenant: tenantId
  };
  const payloadString = JSON.stringify(payload);
  const secret = process.env.ROYALTY_SECRET_HASH;
  // Generate HMAC signature
  const signature = crypto
    .createHmac('sha256', secret)
    .update(payloadString)
    .digest('hex');
  try {
    const response = await axios.post(
      'https://api.royalti.io/webhook/royalty/file-update/webhook',
      payload,
      {
        headers: {
          'Content-Type': 'application/json',
          'royalti-x-hash': signature
        }
      }
    );
    console.log('Webhook sent successfully:', response.data);
  } catch (error) {
    console.error('Webhook failed:', error.message);
  }
}
// Usage
notifyRoyaltiFileProcessed('f47ac10b-58cc-4372-a567-0e02b2c3d479', 123);

{
  "id": "d3f2c1b0-1234-5678-90ab-cdef12345678",
  "status": "done",
  "url": "https://storage.googleapis.com/downloads/export-2024-01-15.csv?signature=..."
}

import hmac
import hashlib
import json
import requests
import os
def notify_download_ready(download_id, status, url):
    payload = {
        "id": download_id,
        "status": status,
        "url": url
    }
    payload_string = json.dumps(payload)
    secret = os.getenv('ROYALTY_SECRET_HASH')
    # Generate HMAC signature
    signature = hmac.new(
        secret.encode('utf-8'),
        payload_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    headers = {
        'Content-Type': 'application/json',
        'royalti-x-hash': signature
    }
    response = requests.post(
        'https://api.royalti.io/webhook/download/status-update/webhook',
        json=payload,
        headers=headers
    )
    print(f"Webhook sent: {response.status_code}")
    return response.json()
# Usage
notify_download_ready(
    download_id='d3f2c1b0-1234-5678-90ab-cdef12345678',
    status='done',
    url='https://storage.googleapis.com/downloads/export.csv'
)

const express = require('express');
const crypto = require('crypto');
const app = express();
// IMPORTANT: Store raw body for signature verification
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf.toString('utf8');
  }
}));
// Webhook signature verification
function verifySignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
// Webhook handler
app.post('/webhooks/royalti', (req, res) => {
  const signature = req.headers['x-royalti-signature'];
  const secret = process.env.ROYALTI_WEBHOOK_SECRET;
  // Verify signature
  if (!verifySignature(req.rawBody, signature, secret)) {
    console.error('Invalid webhook signature');
    return res.status(401).json({ error: 'Invalid signature' });
  }
  const event = req.body;
  console.log(`\nReceived webhook: ${event.event}`);
  console.log(`Delivery ID: ${event.id}`);
  console.log(`Timestamp: ${event.timestamp}`);
  console.log(`Attempt: ${event.delivery.attempt}/${event.delivery.maxAttempts}`);
  // Route to event handlers
  try {
    switch (event.event) {
      case 'Payment completed':
        handlePaymentCompleted(event.data);
        break;
      case 'Track created':
        handleAssetCreated(event.data);
        break;
      case 'Royalty File processed':
        handleRoyaltyFileProcessed(event.data);
        break;
      default:
        console.log(`Unhandled event type: ${event.event}`);
    }
    // Always respond with 200 to acknowledge receipt
    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Error processing webhook:', error);
    // Return 500 to trigger retry
    res.status(500).json({ error: 'Processing failed' });
  }
});
// Event handlers
function handlePaymentCompleted(data) {
  console.log(`\nPayment Completed:`);
  console.log(`  Amount: ${data.attributes.currency} ${data.attributes.amount}`);
  console.log(`  Recipient: ${data.attributes.recipientName}`);
  console.log(`  Method: ${data.attributes.method}`);
  // Your business logic here
  // - Update accounting system
  // - Send confirmation email
  // - Trigger payment notifications
}
function handleAssetCreated(data) {
  console.log(`\nAsset Created:`);
  console.log(`  Title: ${data.attributes.title}`);
  console.log(`  Artists: ${data.attributes.artists.join(', ')}`);
  console.log(`  ISRC: ${data.attributes.isrc}`);
  // Your business logic here
  // - Sync to external catalog
  // - Trigger metadata enrichment
  // - Update content management system
}
function handleRoyaltyFileProcessed(data) {
  console.log(`\nRoyalty File Processed:`);
  console.log(`  Records: ${data.attributes.recordsProcessed}`);
  console.log(`  Total Amount: $${data.attributes.totalAmount}`);
  // Your business logic here
  // - Trigger accounting calculations
  // - Generate reports
  // - Send notifications to stakeholders
}
// Health check endpoint
app.get('/health', (req, res) => {
  res.json({ status: 'ok', service: 'royalti-webhook-handler' });
});
// Start server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook server listening on port ${PORT}`);
  console.log(`Webhook endpoint: http://localhost:${PORT}/webhooks/royalti`);
});

const express = require('express');
const app = express();
// In-memory store (use Redis in production)
const processedEvents = new Set();
const EVENT_TTL = 24 * 60 * 60 * 1000; // 24 hours
app.post('/webhooks/royalti', async (req, res) => {
  const event = req.body;
  const eventId = event.id;
  // Check if we've already processed this event
  if (processedEvents.has(eventId)) {
    console.log(`Duplicate event ${eventId} - returning 200 without processing`);
    return res.status(200).json({ received: true, duplicate: true });
  }
  try {
    // Process the event
    await processEvent(event);
    // Mark as processed
    processedEvents.add(eventId);
    // Clean up old events after TTL
    setTimeout(() => {
      processedEvents.delete(eventId);
    }, EVENT_TTL);
    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Processing failed:', error);
    res.status(500).json({ error: 'Processing failed' });
  }
});
async function processEvent(event) {
  // Your event processing logic
  console.log(`Processing event: ${event.event}`);
  // Simulate async operation
  await new Promise(resolve => setTimeout(resolve, 100));
}

console.log('Received signature:', req.headers['x-royalti-signature']);
console.log('Raw body:', req.rawBody);
console.log('Secret:', process.env.ROYALTI_WEBHOOK_SECRET);
const expectedSignature = 'sha256=' + crypto
  .createHmac('sha256', process.env.ROYALTI_WEBHOOK_SECRET)
  .update(req.rawBody)
  .digest('hex');
console.log('Expected signature:', expectedSignature);
console.log('Match:', expectedSignature === req.headers['x-royalti-signature']);

const queue = [];
app.post('/webhooks/royalti', (req, res) => {
  // Verify signature first
  if (!verifySignature(...)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  // Add to queue for background processing
  queue.push(req.body);
  // Respond immediately
  res.status(200).json({ received: true });
});
// Process queue in background
setInterval(() => {
  while (queue.length > 0) {
    const event = queue.shift();
    processEvent(event).catch(console.error);
  }
}, 1000);

curl -X GET "https://api.royalti.io/webhook-deliveries?status=failed&page=1&size=50" \
  -H "Authorization: Bearer YOUR_TOKEN"