Webhooks
Report verification outcomes back to Novauth so your session records stay accurate. Each channel exposes a dedicated webhook endpoint your server calls after it observes the result.
How it works
Novauth does not push events to your server. Instead, your backend observes the verification outcome (via the mobile SDK, your own app logic, or a status-check poll) and then POSTs the result back to the Connect Hub webhook endpoint.
All webhook endpoints require the same x-api-key header used for regular API requests. Return HTTP 200 to acknowledge.
Verify Call
After your mobile SDK reads the incoming caller ID, report whether the digits matched the expected caller.
uuidstringstatus"Success" | "Failed" | "Incomplete" | "WrongNumber"{
"uuid": "01J8K2M3N4P5Q6R7S8T9U0V1W2",
"status": "Success"
}
// Possible status values:
// "Success" — caller ID matched, user verified
// "Failed" — call was not answered or no match
// "Incomplete" — call dropped before matching
// "WrongNumber" — mismatch detected# After initiating a flash call, POST the result back to Novauth:
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash/webhook \
-H "x-api-key: YOUR_API_KEY" \
-H "x-account-id: YOUR_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"uuid": "01J8K2M3N4P5Q6R7S8T9U0V1W2",
"status": "Success"
}'SMS
Once your server confirms the user entered the correct OTP code, report the delivery status back to Novauth.
idstringstatus"delivered" | "sent" | "failed" | "undelivered"{
"id": "msg_01J8K2M3N4P5Q6R7S8T9",
"status": "delivered"
}
// Possible status values (from carrier):
// "delivered" — confirmed delivery to handset
// "sent" — dispatched to carrier, awaiting DLR
// "failed" — delivery failed (invalid number, blocked, etc.)
// "undelivered" — carrier accepted but delivery not confirmedcurl -X POST https://api.novauth.com/api/v1/connect-hub/sms/webhook \
-H "x-api-key: YOUR_API_KEY" \
-H "x-account-id: YOUR_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"id": "msg_01J8K2M3N4P5Q6R7S8T9",
"status": "delivered"
}'Report WhatsApp OTP delivery outcome. Only two statuses are possible.
uuidstringstatus"Success" | "Failed"{
"uuid": "01J8K2M3N4P5Q6R7S8T9U0V1W2",
"status": "Success"
}
// Only two status values:
// "Success" — WhatsApp OTP delivered to user
// "Failed" — delivery failed (user not on WhatsApp, etc.)curl -X POST https://api.novauth.com/api/v1/connect-hub/whatsapp/webhook \
-H "x-api-key: YOUR_API_KEY" \
-H "x-account-id: YOUR_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"uuid": "01J8K2M3N4P5Q6R7S8T9U0V1W2",
"status": "Success"
}'Telegram OTP
Report Telegram message delivery. Use POST /check-verification-status for server-side code validation — see the Telegram OTP quickstart for the full flow.
idstringstatus"Success" | "Failed"{
"id": "01J8K2M3N4P5Q6R7S8T9U0V1W2",
"status": "Success"
}
// Only two status values:
// "Success" — Telegram message delivered
// "Failed" — delivery failed (user blocked bot, etc.)curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/webhook \
-H "x-api-key: YOUR_API_KEY" \
-H "x-account-id: YOUR_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"id": "01J8K2M3N4P5Q6R7S8T9U0V1W2",
"status": "Success"
}'Telegram Gateway inbound
When you pass a callback_url in your Telegram send request, Telegram's Gateway will POST verification status events directly to that URL. Unlike the other channels, you are the receiver — and Telegram signs every request with HMAC-SHA256.
X-Request-TimestampUnix epoch seconds (integer). Reject if |now − timestamp| > 300.X-Request-SignatureHex-encoded HMAC-SHA256. Verify with timing-safe comparison.secret = SHA256(access_token) · data = "{timestamp}\n{rawBody}" · sig = HMAC-SHA256(secret, data)// Telegram Gateway sends status updates to your callback_url
// when you provided it in the original send request.
// Payload (example):
{
"request_id": "tg_req_abc123",
"phone_number": "+14155552671",
"status": "code_valid",
"verification_status": {
"status": "code_valid",
"updated_at": 1713350400
}
}
// status values:
// "code_valid" — user entered correct code
// "code_invalid" — wrong code entered
// "code_max_attempts_exceeded" — too many attempts
// "expired" — TTL elapsed before entryimport { createHmac, timingSafeEqual } from 'node:crypto';
app.post('/telegram/gateway-callback', express.raw({ type: '*/*' }), (req, res) => {
const timestamp = req.headers['x-request-timestamp'];
const signature = req.headers['x-request-signature'];
const rawBody = req.body; // must be raw Buffer
// 1. Replay-attack guard — reject requests older than 5 minutes
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
return res.status(401).json({ error: 'Request expired' });
}
// 2. Derive signing secret: SHA256 of your Telegram Gateway access token
const secret = createHmac('sha256', '')
.update(process.env.TELEGRAM_GATEWAY_TOKEN)
.digest();
// 3. Compute expected signature
const data = `${timestamp}\n${rawBody}`;
const expected = createHmac('sha256', secret).update(data).digest('hex');
// 4. Timing-safe comparison
const sigBuf = Buffer.from(signature ?? '', 'hex');
const expBuf = Buffer.from(expected, 'hex');
if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const payload = JSON.parse(rawBody.toString());
console.log('Telegram Gateway event:', payload.status);
res.status(200).json({ ok: true });
});Always parse the body after signature verification, and parse it from the raw byte buffer — not from a pre-parsed JSON object. JSON re-serialization can alter byte order and break the HMAC.