Webhooks

Use this page to configure durable webhook delivery for LicenseKit events.

Who This Is For

• teams syncing LicenseKit activity into another system
• developers implementing webhook receivers
• operators monitoring delivery health

When To Use This

Use webhooks when another system should react to LicenseKit events without polling.

How It Works

Webhook configuration routes:

• GET /api/v1/webhooks
• POST /api/v1/webhooks
• GET /api/v1/webhooks/{id}
• PATCH /api/v1/webhooks/{id}
• DELETE /api/v1/webhooks/{id}

Current scope:

• webhook:write

Delivery model:

• endpoint configuration is managed through the API
• deliveries are queued durably
• failures are retried
• webhook payloads are signed with an HMAC header

Current limitation:

• there is no first-class delivery history API or manual replay endpoint in the shipped surface
• aggregate health is available through GET /api/v1/ops/webhook-health

Example

Create an endpoint:

curl -X POST https://api.licensekit.dev/api/v1/webhooks \
  -H "Authorization: Bearer $LICENSEKIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary",
    "url": "https://your-app.example/webhooks/licensekit",
    "event_types": ["license.activated", "license.suspended"],
    "is_active": true
  }'

Important delivery headers:

• X-Locksmith-Delivery-ID
• X-Locksmith-Event-Sequence
• X-Locksmith-Event-Type
• X-Locksmith-Signature

Signature payload format:

<timestamp>.<delivery_id>.<raw_request_body>

Common Mistakes

• verifying the signature against reserialized JSON instead of the raw body
• treating delivery as exactly-once instead of at-least-once
• expecting webhook reads to use a separate webhook:read scope today

Related Pages

• Events
• Error Handling
• Health And Readiness