Webhooks Reference

Inbound webhook endpoints for receiving events from external services. For a deep dive into signature verification and event handling, see Webhooks Deep Dive.

Base path: /api/v1/webhooks/

POST /api/v1/webhooks/scaikey#

Receives identity lifecycle events from ScaiKey — partner, tenant, user, group, and application-assignment changes.

Authentication: HMAC signature. Caller sends:

• X-ScaiKey-Signature: t=<timestamp>,v1=<hmac_sha256_hex>
• X-ScaiKey-Event-Id: <unique_event_id> (optional; for idempotency)
• X-ScaiKey-Event-Type: <event_type> (optional; duplicated in body)

The signature is computed as HMAC-SHA256(SCAIKEY_WEBHOOK_SECRET, "{timestamp}.{raw_body}"). A 5-minute timestamp freshness check prevents replay.

Request body:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "event_id": "evt_abc123",
  "event_type": "user.created",
  "timestamp": "2026-04-23T10:42:00Z",
  "data": {
    "id": "usr_abc",
    "email": "user@example.com",
    "first_name": "First",
    "last_name": "Last",
    "status": "ACTIVE",
    "tenant": {
      "id": "tnt_xyz",
      "name": "BBinfra NL",
      "slug": "bbinfra-nl"
    }
  }
}

Response: 200 OK

1
2
3
4
5

{
  "success": true,
  "message": "Event user.created processed successfully",
  "event_id": "evt_abc123"
}

Processing errors return 200 with success: false to prevent retry loops — check logs for details.

Supported event types#

Partner events#

Tenant events#

User events#

Group events#

Application events#

Event delivery#

• Scope. ScaiKey sends events only for users and groups assigned to the ScaiDNS application, plus all tenants and partners.
• Retry. ScaiKey retries on 5xx or non-2xx responses, with exponential backoff.
• Order. Not strictly guaranteed. Your handler must be idempotent.
• Duplicates. Possible on retries. Use event_id if you need strict deduplication — ScaiDNS currently does not dedupe on receipt.

Configuring the webhook#

Two sides need configuration:

ScaiKey side: Register the webhook URL (https://your-scaidns.example.com/api/v1/webhooks/scaikey) and signing secret in ScaiKey's admin UI.

ScaiDNS side: Set SCAIKEY_WEBHOOK_SECRET in .env to the same value. Restart the API server.

The secret is used by ScaiDNS to verify signatures. If it's unset, signature verification is skipped with a warning — intended for local development, never for production.

Errors#

Related#

• Webhooks Deep Dive — signature implementation, debugging.
• Tenants and Users — how identities sync.