LicenseChain

Webhooks

Receive real-time notifications about events in your LicenseChain account. Automate workflows and keep your application in sync.

LicenseChain uses separate signing channels for Core API webhooks, Pay merchant webhooks, and Mirror redirect HMAC (see Mirror SDK).

Why Use Webhooks?

Webhook Benefits

Real-time Updates

  • Instant notifications when events occur
  • No need to poll our API repeatedly
  • Reduced API usage and costs
  • Better user experience with immediate updates

Automation

  • Trigger custom actions in your application
  • Sync data across different systems
  • Automate customer communication (e.g., expiration reminders)
  • Integrate with third-party services

Available Events

License Events

  • `license.created` - A new license is generated
  • `license.updated` - A license's properties are changed
  • `license.expired` - A license has reached its expiration date
  • `license.revoked` - A license is manually revoked
  • `license.deleted` - A license is permanently removed
  • `license.transferred` - A license is moved to another user/app

Payment Events

  • `payment.succeeded` - A payment is successfully processed
  • `payment.failed` - A payment attempt failed
  • `subscription.created` - A new subscription is started
  • `subscription.updated` - A subscription's details are changed
  • `subscription.canceled` - A subscription is canceled (Pay webhook; cancel via POST /v1/subscriptions/:id/cancel when API route is deployed)
  • `invoice.paid` - An invoice is marked as paid

Implementation Steps

1. Configure Webhook Endpoint

Set up a URL in your LicenseChain dashboard or via the API where events will be sent. 

// Via Dashboard
1. Go to Settings > Webhooks
2. Click "Add Endpoint"
3. Enter your URL (e.g., https://your-app.com/webhooks/licensechain)
4. Select the events you want to receive (e.g., license.created, license.updated)
5. Save configuration

// Via API
// Create webhook with URL and events
// Set webhook endpoint
// Select events to receive

2. Implement Webhook Handler

Create an endpoint in your application to handle incoming webhook events. 

// Express.js example
// Handle webhook endpoint
// Get signature from headers
// Verify webhook signature
// Process different event types
// Return success response

3. Verify Webhook Signature

Always verify webhook signatures to ensure the request came from LicenseChain. 

// Import crypto module
// Create webhook signature verification function
// Generate expected signature using HMAC
// Compare signatures securely
// Return verification result

Best Practices

  • Asynchronous Processing - Respond to webhooks immediately (within 3 seconds) and process events asynchronously in a background job.
  • Idempotency - Design your event handlers to be idempotent to safely process duplicate events.
  • Error Handling & Retries - Implement robust error handling and leverage LicenseChain's automatic retry mechanism for failed deliveries.
  • Security - Always verify webhook signatures to prevent spoofing attacks. Use HTTPS for your endpoint.
  • Monitoring - Monitor your webhook endpoint for errors and delivery failures.