Webhooks

Nani sends signed HTTP POST requests when verification events occur.

Configure an endpoint

POST

/v1/webhooks

curl -X POST http://localhost:3002/v1/webhooks \
  -H "x-api-key: sk_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/nani",
    "events": ["session.approved", "session.rejected", "session.review_required"]
  }'

Response

{
  "webhook_id": "wh_01",
  "url": "https://your-app.com/webhooks/nani",
  "events": ["session.approved", "session.rejected", "session.review_required"],
  "status": "active"
}

Verify signatures

Each request includes x-nani-signature — an HMAC-SHA256 of the raw body using your webhook secret.

Verifying a request

import crypto from 'crypto'

export function verifyNaniSignature(body, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(body).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}

Common events

Event	When
`session.approved`	Verification succeeded
`session.rejected`	Verification failed
`session.review_required`	Manual review needed
`session.expired`	Session TTL exceeded
`identity.created`	New identity vaulted

See Webhooks API for delivery logs and management endpoints.