Webhooks

⚠️

Coming Soon — Webhooks are a planned feature and are not yet available. This page documents the intended design. The API and payload formats described below are subject to change before release.

Overview

Webhooks will allow you to receive real-time notifications when events occur on your licenses. Instead of polling the GET /status endpoint, you will be able to register a webhook URL and receive HTTP POST requests whenever a license event happens.

This is especially useful for:

Syncing license status with your own database
Triggering automated workflows when a license is activated or deactivated
Receiving alerts when a license is suspended or revoked
Building real-time dashboards that reflect license activity

Planned Events

The following webhook events are planned:

Event	Description
`license.activated`	A domain has been activated on a license
`license.verified`	A license verification was performed
`license.deactivated`	A domain has been deactivated from a license
`license.suspended`	A license has been suspended
`license.revoked`	A license has been permanently revoked

Webhook Payload Format (Preview)

All webhook payloads will follow a consistent structure:

{
  "event": "license.activated",
  "timestamp": "2026-03-15T10:30:00Z",
  "data": {
    "license_key": "LIC-A3F9-K2M7-P8X1-Q4R6",
    "status": "active",
    "domain": "myapp.example.com",
    "product": {
      "id": 42,
      "title": "DeFi Dashboard Pro",
      "slug": "defi-dashboard-pro"
    }
  }
}

Event-Specific Data

The data object will contain different fields depending on the event type:

license.activated and license.deactivated

{
  "event": "license.activated",
  "timestamp": "2026-03-15T10:30:00Z",
  "data": {
    "license_key": "LIC-A3F9-K2M7-P8X1-Q4R6",
    "status": "active",
    "domain": "myapp.example.com",
    "domains_used": 2,
    "max_domains": 3
  }
}

license.suspended and license.revoked

{
  "event": "license.suspended",
  "timestamp": "2026-03-15T10:30:00Z",
  "data": {
    "license_key": "LIC-A3F9-K2M7-P8X1-Q4R6",
    "status": "suspended",
    "reason": "Terms of service violation"
  }
}

Signature Verification (Planned)

All webhook requests will include a signature header for verifying authenticity. The planned implementation:

Each webhook endpoint registration will generate a unique webhook secret.
Every webhook request will include an X-Web3Market-Signature header.
The signature will be an HMAC-SHA256 hash of the raw request body, using the webhook secret as the key.

X-Web3Market-Signature: sha256=a1b2c3d4e5f6...

Verification example (pseudocode):

const crypto = require('crypto');
 
function verifyWebhookSignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Always verify the webhook signature before processing the payload. This prevents attackers from sending fake webhook events to your endpoint.

Delivery and Retry Policy (Planned)

Webhooks will be delivered via HTTP POST with a Content-Type: application/json header.
Your endpoint must respond with a 2xx status code within 30 seconds to acknowledge receipt.
Failed deliveries will be retried up to 5 times with exponential backoff (1 min, 5 min, 30 min, 2 hours, 12 hours).
After all retries are exhausted, the webhook will be marked as failed and a notification will be sent to your dashboard.

Stay Updated

Webhooks are actively being developed. Follow the Web3.Market changelog for announcements on the release timeline.

GET /status Error Codes