Webhooks

KolayLogin fires webhooks when significant events happen in your app — user creation, session sign-outs, organization invites, subscription updates. Deliveries are signed with HMAC-SHA256 and retried on failure.

Copy this quickstart guide as a prompt for LLMs to implement KolayLogin in your application.

Configure an endpoint

Dashboard → app → Webhooks → Add endpoint.
Provide the destination URL and (optionally) an event allowlist.
Copy the generated signing secret into your server's environment.

Payload shape

{
  "id": "evt_...",
  "type": "user.created",
  "environmentId": "...",
  "appId": "...",
  "data": { /* event-specific */ },
  "createdAt": "2026-04-24T12:34:56.000Z"
}

Verify the signature

Each request arrives with headers x-kl-webhook-signature and x-kl-webhook-timestamp. Recompute the HMAC and compare in constant time — or just use the helper from @kolaylogin/backend:

import { assertWebhookSignature } from '@kolaylogin/backend';

app.post('/hooks/kolaylogin', express.text({ type: '*/*' }), (req, res) => {
  try {
    assertWebhookSignature({
      headers: req.headers,
      rawBody: req.body,
      secret: process.env.KL_WEBHOOK_SECRET!,
    });
  } catch (e: any) {
    return res.status(401).json({ error: e.message });
  }
  const evt = JSON.parse(req.body);
  switch (evt.type) {
    case 'user.created':
      // ... mirror to your own DB
      break;
  }
  res.sendStatus(200);
});

Use the RAW body

The signature is computed over the raw request bytes. If your framework pre-parses JSON, re-stringify or configure it to keep the raw body. Fastify users can enable the fastify-raw-body plugin (KolayLogin does this internally for the Stripe webhook).

Retry policy

Non-2xx responses (or connection failures) are retried with exponential backoff up to 8 times over roughly 24 hours. Each attempt is persisted in the delivery log — inspect them from the dashboard Events tab.

Available event types

user.created, user.updated, user.deleted
session.created, session.ended
organization.created, organization.member.invited, organization.member.joined
subscription.created, subscription.updated, invoice.paid

← Previous

Organizations

Billing & plans