Webhooks
Segnala gli esiti della verifica a Novauth affinché i record di sessione rimangano accurati. Ogni canale espone un endpoint webhook dedicato che il tuo server chiama dopo aver osservato il risultato.
Come funziona
Novauth non invia eventi push al tuo server. Il tuo backend osserva invece l'esito della verifica (tramite SDK mobile, logica applicativa o polling di controllo stato) e poi invia tramite POST il risultato all'endpoint webhook del Connect Hub.
Tutti gli endpoint webhook richiedono lo stesso header x-api-key usato per le normali richieste API. Restituisci HTTP 200 per confermare la ricezione.
Verify Call
Dopo che il tuo SDK mobile ha letto l'ID chiamante in arrivo, segnala se le cifre corrispondevano al chiamante atteso.
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
Una volta che il tuo server conferma che l'utente ha inserito il codice OTP corretto, segnala lo stato di consegna a 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"
}'Segnala l'esito della consegna dell'OTP WhatsApp. Sono possibili solo due stati.
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"
}'OTP Telegram
Segnala la consegna del messaggio Telegram. Usa POST /check-verification-status per la validazione del codice lato server — consulta l'avvio rapido OTP Telegram per il flusso completo.
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"
}'Inbound di Telegram Gateway
Quando passi un callback_url nella tua richiesta di invio Telegram, il Gateway di Telegram invierà tramite POST gli eventi di stato della verifica direttamente a quell'URL. A differenza degli altri canali, sei tu il destinatario — e Telegram firma ogni richiesta con HMAC-SHA256.
X-Request-TimestampSecondi epoch Unix (intero). Rifiuta se |ora − timestamp| > 300.X-Request-SignatureHMAC-SHA256 codificato in esadecimale. Verifica con confronto time-safe.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 });
});Analizza sempre il corpo dopo la verifica della firma e analizzalo dal buffer di byte grezzo — non da un oggetto JSON pre-analizzato. La riseriazzazione JSON può alterare l'ordine dei byte e invalidare l'HMAC.