// API Reference

Webhooks

Receive real-time HMAC-SHA256 signed notifications for verification events.

Overview

Osapher sends HMAC-SHA256 signed HTTP POST requests to your registered endpoint whenever a verification event occurs. This allows your system to react in real time without polling the API.

Webhooks require a Growth or Enterprise plan. Register endpoints at enterprise.osapher.com/webhooks.

Registering endpoints

Go to enterprise.osapher.com/webhooks and click Add Webhook. Enter your HTTPS endpoint URL and select the events you want to receive.

Each endpoint is assigned a unique signing secret (whsec_...). Use this secret to verify the signature of every incoming request.

Event types

EventFired when
verification.completedA verification finishes with any result
verification.high_riskFracture Score exceeds 50
certificate.issuedA KYB certificate is issued by an officer
onboarding.submittedAn applicant completes the onboarding portal
certificate.expiredA certificate passes its expiry date

Payload shape

payload
{
  "event": "verification.completed",
  "timestamp": "2026-04-26T10:23:01.000Z",
  "data": {
    "legalName": "Acme Corp Pty Ltd",
    "abn": "22222222222",
    "jurisdiction": "AU",
    "fractureScore": 0,
    "fractureRisk": "low",
    "status": "verified"
  }
}

Verifying signatures

Every webhook includes an X-Osapher-Signature header with the format sha256=.... Verify it using your endpoint's signing secret:

node.js
const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' +
    crypto
      .createHmac('sha256', secret)
      .update(payload)
      .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

// In your endpoint handler:
app.post('/webhooks/verinty', (req, res) => {
  const signature = req.headers['x-verinty-signature']
  const isValid = verifyWebhook(
    req.rawBody,
    signature,
    process.env.WEBHOOK_SECRET
  )

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' })
  }

  const event = req.body
  console.log('Received:', event.event, event.data)
  res.status(200).json({ received: true })
})

Always verify signatures before processing webhook payloads. Reject any request that fails signature verification.

Retry behaviour

If your endpoint returns a non-200 response or times out (10 second timeout), Osapher records a failed delivery and increments the failure counter on your webhook. Failed deliveries are not automatically retried — monitor your failure count in the webhooks portal.

Return 200 as quickly as possible and process the event asynchronously.

Verify EntityFracture Score™