Events & Webhooks

Every security-relevant action AuthKit performs (logins, signups, MFA changes, PAT issuance, client CRUD, impersonation, …) is emitted as an audit event. Beyond the pluggable audit sink that persists them, the host can observe the same stream in real time through events:

• onEvent — an in-process callback invoked for every event (forward to a bus, a logger, an analytics pipeline).
• webhook — an HTTP POST of the event JSON to an external URL, optionally HMAC-signed.

Both are best-effort and fire-and-forget: a failing handler or an unreachable webhook never throws into the request path.

Configuration

import { defineConfig } from '@adonis-agora/authkit-server'

export default defineConfig({
  // ...issuer, clients, accountStore, etc.

  // Optional: persist events for the admin console / queries.
  audit: lucidAuditSink(AuthEvent),

  events: {
    onEvent: async (event) => {
      // event: { type, accountId, email, clientId, actorId, ip, metadata }
      await myBus.publish('authkit', event)
    },
    webhook: {
      url: 'https://hooks.example.com/authkit',
      secret: process.env.AUTHKIT_WEBHOOK_SECRET, // optional, enables signing
    },
  },
})

When events is set, the resolved audit sink becomes a fan-out: each record is written to the original sink (if any) and dispatched to onEvent and the webhook. The original sink's list() (admin queries) is preserved.

Webhook payload

The body is JSON:

{
  "type": "login.success",
  "accountId": "user-1",
  "email": "user@example.com",
  "clientId": "app1",
  "orgId": null,
  "ip": "203.0.113.7",
  "metadata": { "mfa": "totp" },
  "ts": "2026-06-04T12:00:00.000Z"
}

orgId is the organization (tenant) the event belongs to, or null. It is a first-class field, not a metadata key — see Provisioning your own database for why that distinction matters.

Sent with content-type: application/json. The request has a 5s timeout (via AbortSignal) and is never awaited by the request that triggered it.

Signature verification

When webhook.secret is set, AuthKit adds a header:

x-authkit-signature: sha256=<hex HMAC-SHA256 of the raw body>

Verify it on the receiver before trusting the payload:

import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(rawBody: string, header: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(header)
  const b = Buffer.from(expected)
  return a.length === b.length && timingSafeEqual(a, b)
}

Event types

Every AuditEvent carries accountId, email, clientId, actorId (impersonation), ip, and free-form metadata. The timestamp is set by the sink.

AuditEventType is derived from AUDIT_EVENT_TYPES, a const array exported from @adonis-agora/authkit-server. Import it when you need the set at runtime — to seed a filter UI, to validate stored rows, or to assert your own switch still covers everything:

import { AUDIT_EVENT_TYPES, type AuditEventType } from '@adonis-agora/authkit-server'

const SECURITY_CRITICAL: AuditEventType[] = AUDIT_EVENT_TYPES.filter(
  (type) => type.startsWith('impersonation') || type.startsWith('mfa.'),
)

The union being derived from a value, rather than written out by hand, is what lets the library check itself: a spec scans every audit.record() call site and fails when an event is emitted that the list does not declare.

Provisioning your own database

You do not need any other Agora library to react to what the IdP does. Both onEvent and the webhook receive the complete event, so a host can keep its own tables in sync — create a companies row when an organization is created, revoke an app-side membership when a member is removed, and so on:

defineConfig({
  // …
  events: {
    onEvent: async (event) => {
      if (event.type === 'organization.created') {
        await Company.create({ authOrgId: event.orgId!, slug: event.metadata?.slug as string })
      }
      if (event.type === 'organization.member_removed') {
        await Membership.query()
          .where('company_id', event.orgId!)
          .where('user_id', event.metadata?.targetAccountId as string)
          .delete()
      }
    },
  },
})

Use event.orgId — not event.metadata.orgId — as the tenant key. Both are populated on organization events, but only the first-class field is guaranteed across every delivery channel:

The last row is the reason orgId is promoted: the diagnostics bus mirrors every audit event for Telescope and any onDiagnostic('authkit', …) subscriber, and that mirror is stripped of PII (email, ip, and the free-form metadata, which may carry an invitee's address). Only the opaque internal ids survive — accountId, actorId, clientId, orgId. That keeps a bus subscriber able to answer which tenant without ever seeing personal data.