Webhook Event Types

This page documents all webhook events you can subscribe to.

Box Events

box.created

Fired when a new identity is boxed.

{
  "id": "evt_abc123",
  "type": "box.created",
  "createdAt": "2024-01-15T10:00:00Z",
  "data": {
    "boxId": "box_xyz789",
    "claimId": "claim_123456",
    "identityName": "Taylor Swift",
    "entityType": "INDIVIDUAL",
    "policy": "MONETIZE",
    "enforcement": "MODERATE",
    "policyConfig": {
      "royaltyRate": 0.10,
      "revenueTypes": ["subscription", "per_message", "tips"]
    }
  }
}

When to use: Scan your existing avatars for matches when a new identity is boxed.

box.updated

Fired when a box’s policy or configuration changes.

{
  "id": "evt_abc124",
  "type": "box.updated",
  "createdAt": "2024-01-16T10:00:00Z",
  "data": {
    "boxId": "box_xyz789",
    "changes": {
      "policy": {
        "from": "MONETIZE",
        "to": "BLOCK_ALL"
      },
      "enforcement": {
        "from": "MODERATE",
        "to": "STRICT"
      }
    }
  }
}

When to use: Update your handling of existing avatars if policy becomes more restrictive.

box.deleted

Fired when a box is removed.

{
  "id": "evt_abc125",
  "type": "box.deleted",
  "createdAt": "2024-01-17T10:00:00Z",
  "data": {
    "boxId": "box_xyz789",
    "claimId": "claim_123456",
    "identityName": "Taylor Swift"
  }
}

When to use: Identity is no longer protected. Existing licenses may remain valid.

Violation Events

violation.detected

Fired when a violation is detected on your platform.

{
  "id": "evt_def123",
  "type": "violation.detected",
  "createdAt": "2024-01-15T10:00:00Z",
  "data": {
    "violationId": "viol_abc123",
    "boxId": "box_xyz789",
    "identityName": "Taylor Swift",
    "policy": "MONETIZE",
    "avatar": {
      "id": "avatar_123",
      "name": "Taylor AI",
      "creatorId": "creator_456"
    },
    "detection": {
      "confidence": 0.95,
      "classification": "EXACT_MATCH"
    },
    "gracePeriod": {
      "id": "gp_abc123",
      "expiresAt": "2024-02-14T10:00:00Z"
    }
  }
}

When to use: Notify avatar creators and start compliance tracking.

violation.resolved

Fired when a violation is resolved.

{
  "id": "evt_def124",
  "type": "violation.resolved",
  "createdAt": "2024-01-20T10:00:00Z",
  "data": {
    "violationId": "viol_abc123",
    "resolution": "licensed",
    "licenseId": "lic_xyz789",
    "avatarId": "avatar_123"
  }
}

violation.appealed

Fired when a violation is appealed.

{
  "id": "evt_def125",
  "type": "violation.appealed",
  "createdAt": "2024-01-16T10:00:00Z",
  "data": {
    "violationId": "viol_abc123",
    "appealId": "appeal_xyz789",
    "reason": "parody",
    "gracePeriodPaused": true
  }
}

Grace Period Events

grace_period.started

Fired when a grace period begins.

{
  "id": "evt_ghi123",
  "type": "grace_period.started",
  "createdAt": "2024-01-15T10:00:00Z",
  "data": {
    "gracePeriodId": "gp_abc123",
    "boxId": "box_xyz789",
    "identityName": "Taylor Swift",
    "expiresAt": "2024-02-14T10:00:00Z",
    "affectedAvatars": [
      {
        "avatarId": "avatar_123",
        "name": "Taylor AI",
        "creatorId": "creator_456",
        "userCount": 5000
      }
    ]
  }
}

When to use: Notify affected avatar creators and their users.

grace_period.reminder

Fired at reminder intervals (day 7, 21, 28).

{
  "id": "evt_ghi124",
  "type": "grace_period.reminder",
  "createdAt": "2024-01-22T10:00:00Z",
  "data": {
    "gracePeriodId": "gp_abc123",
    "reminderDay": 7,
    "daysRemaining": 23,
    "affectedAvatars": [...]
  }
}

grace_period.ending

Fired 2 days before expiration.

{
  "id": "evt_ghi125",
  "type": "grace_period.ending",
  "createdAt": "2024-02-12T10:00:00Z",
  "data": {
    "gracePeriodId": "gp_abc123",
    "expiresAt": "2024-02-14T10:00:00Z",
    "daysRemaining": 2,
    "unresolvedAvatars": [...]
  }
}

When to use: Send urgent notifications to non-compliant avatar creators.

grace_period.expired

Fired when grace period expires without resolution.

{
  "id": "evt_ghi126",
  "type": "grace_period.expired",
  "createdAt": "2024-02-14T10:00:00Z",
  "data": {
    "gracePeriodId": "gp_abc123",
    "action": "enforce",
    "avatarsToDeactivate": [
      {
        "avatarId": "avatar_123",
        "userCount": 5000
      }
    ]
  }
}

When to use: Deactivate non-compliant avatars and notify users.

grace_period.resolved

Fired when all violations in a grace period are resolved.

{
  "id": "evt_ghi127",
  "type": "grace_period.resolved",
  "createdAt": "2024-01-20T10:00:00Z",
  "data": {
    "gracePeriodId": "gp_abc123",
    "resolutions": [
      { "avatarId": "avatar_123", "resolution": "licensed" },
      { "avatarId": "avatar_456", "resolution": "removed" }
    ]
  }
}

License Events

license.requested

Fired when a license is requested.

{
  "id": "evt_jkl123",
  "type": "license.requested",
  "createdAt": "2024-01-15T10:00:00Z",
  "data": {
    "requestId": "req_abc123",
    "boxId": "box_xyz789",
    "platformId": "your_platform",
    "tier": "commercial",
    "useCase": "AI companion platform"
  }
}

license.approved

Fired when a license request is approved.

{
  "id": "evt_jkl124",
  "type": "license.approved",
  "createdAt": "2024-01-17T10:00:00Z",
  "data": {
    "requestId": "req_abc123",
    "licenseId": "lic_xyz789",
    "boxId": "box_xyz789",
    "tier": "commercial",
    "monthlyFee": 500,
    "validFrom": "2024-01-17T00:00:00Z",
    "expiresAt": "2025-01-17T00:00:00Z"
  }
}

license.denied

Fired when a license request is denied.

{
  "id": "evt_jkl125",
  "type": "license.denied",
  "createdAt": "2024-01-16T10:00:00Z",
  "data": {
    "requestId": "req_abc123",
    "boxId": "box_xyz789",
    "reason": "Use case not aligned with brand guidelines"
  }
}

license.expiring

Fired 30 days before license expiration.

{
  "id": "evt_jkl126",
  "type": "license.expiring",
  "createdAt": "2024-12-17T10:00:00Z",
  "data": {
    "licenseId": "lic_xyz789",
    "expiresAt": "2025-01-17T00:00:00Z",
    "daysRemaining": 30,
    "autoRenew": false
  }
}

license.expired

Fired when a license expires.

{
  "id": "evt_jkl127",
  "type": "license.expired",
  "createdAt": "2025-01-17T00:00:00Z",
  "data": {
    "licenseId": "lic_xyz789",
    "boxId": "box_xyz789",
    "gracePeriodId": "gp_new123"
  }
}

license.revoked

Fired when a license is revoked by the identity owner.

{
  "id": "evt_jkl128",
  "type": "license.revoked",
  "createdAt": "2024-06-15T10:00:00Z",
  "data": {
    "licenseId": "lic_xyz789",
    "boxId": "box_xyz789",
    "reason": "Terms violation",
    "gracePeriodId": "gp_abc456"
  }
}

Detection Events

detection.match_found

Fired when a scan finds a potential match (for scan operations).

{
  "id": "evt_mno123",
  "type": "detection.match_found",
  "createdAt": "2024-01-15T10:00:00Z",
  "data": {
    "scanId": "scan_abc123",
    "matches": [
      {
        "avatarId": "avatar_789",
        "matchedBoxId": "box_xyz789",
        "confidence": 0.92
      }
    ]
  }
}

detection.scan_complete

Fired when a platform-wide scan completes.

{
  "id": "evt_mno124",
  "type": "detection.scan_complete",
  "createdAt": "2024-01-15T10:30:00Z",
  "data": {
    "scanId": "scan_abc123",
    "avatarsScanned": 10000,
    "matchesFound": 47,
    "duration": 1800
  }
}

Subscribing to Events

Subscribe to specific events when creating webhooks:

await lmif.webhooks.create({
  url: 'https://yoursite.com/webhooks/lmif',
  events: [
    'box.created',
    'grace_period.started',
    'grace_period.ending',
    'grace_period.expired',
    'license.approved',
    'license.denied'
  ]
});