Riferimento

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.

1
Avvia
Il tuo server avvia una verifica tramite l'API del canale.
2
Azione utente
L'utente riceve e agisce sull'OTP (chiamata, SMS, messaggio nell'app).
3
Osserva l'esito
Il tuo SDK mobile o la logica dell'app rileva successo o fallimento.
4
Segnala il risultato
Il tuo server invia tramite POST uuid + status all'endpoint webhook.

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.

POST/api/v1/connect-hub/call/flash/webhook
uuidstring
UUID restituito da POST /call/flash
status"Success" | "Failed" | "Incomplete" | "WrongNumber"
Esito osservato della chiamata
Payload
json
{
  "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
Esempio — invio risultato
bash
# 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.

POST/api/v1/connect-hub/sms/webhook
idstring
messageId restituito da POST /sms
status"delivered" | "sent" | "failed" | "undelivered"
Stato di consegna SMS dal DLR dell'operatore
Payload
json
{
  "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 confirmed
bash
curl -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"
  }'

WhatsApp

Segnala l'esito della consegna dell'OTP WhatsApp. Sono possibili solo due stati.

POST/api/v1/connect-hub/whatsapp/webhook
uuidstring
UUID restituito da POST /whatsapp/otp
status"Success" | "Failed"
Esito della consegna WhatsApp
json
{
  "uuid": "01J8K2M3N4P5Q6R7S8T9U0V1W2",
  "status": "Success"
}

// Only two status values:
// "Success"  — WhatsApp OTP delivered to user
// "Failed"   — delivery failed (user not on WhatsApp, etc.)
bash
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.

POST/api/v1/connect-hub/telegram/webhook
idstring
UUID restituito da POST /telegram
status"Success" | "Failed"
Esito della consegna Telegram
json
{
  "id": "01J8K2M3N4P5Q6R7S8T9U0V1W2",
  "status": "Success"
}

// Only two status values:
// "Success"  — Telegram message delivered
// "Failed"   — delivery failed (user blocked bot, etc.)
bash
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.

Header di firma
X-Request-TimestampSecondi epoch Unix (intero). Rifiuta se |ora − timestamp| > 300.
X-Request-SignatureHMAC-SHA256 codificato in esadecimale. Verifica con confronto time-safe.
Algoritmo di firma: secret = SHA256(access_token) · data = "{timestamp}\n{rawBody}" · sig = HMAC-SHA256(secret, data)
Esempio di payload evento
json
// 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 entry
Handler di verifica firma
javascript
import { 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.