Referenca

Webhooks

Prijavljujte ishode verifikacije nazad Novauth-u kako bi zapisi vaših sesija ostali tačni. Svaki kanal izlaže namenski webhook endpoint koji vaš server poziva nakon što uoči rezultat.

Kako radi

Novauth ne šalje događaje vašem serveru. Umesto toga, vaš backend uočava ishod verifikacije (preko mobilnog SDK-a, sopstvene logike aplikacije ili provere statusa) i zatim POST-uje rezultat nazad na Connect Hub webhook endpoint.

1
Pokretanje
Vaš server pokreće verifikaciju preko API-ja kanala.
2
Akcija korisnika
Korisnik prima OTP i postupa po njemu (poziv, SMS, poruka u aplikaciji).
3
Uočavanje ishoda
Vaš mobilni SDK ili logika aplikacije detektuje uspeh ili neuspeh.
4
Prijavljivanje rezultata
Vaš server POST-uje uuid + status na webhook endpoint.

Svi webhook endpointi zahtevaju isto x-api-key zaglavlje koje se koristi za redovne API zahteve. Vratite HTTP 200 kao potvrdu prijema.

Verify Call

Nakon što vaš mobilni SDK pročita dolazni ID pozivaoca, prijavite da li su se cifre poklopile sa očekivanim pozivaocem.

POST/api/v1/connect-hub/call/flash/webhook
uuidstring
UUID koji vraća POST /call/flash
status"Success" | "Failed" | "Incomplete" | "WrongNumber"
Uočeni ishod poziva
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
Primer — slanje rezultata
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

Kada vaš server potvrdi da je korisnik uneo ispravan OTP kod, prijavite status isporuke nazad Novauth-u.

POST/api/v1/connect-hub/sms/webhook
idstring
messageId koji vraća POST /sms
status"delivered" | "sent" | "failed" | "undelivered"
Status isporuke SMS-a iz DLR-a operatera
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

Prijavite ishod isporuke WhatsApp OTP-a. Moguća su samo dva statusa.

POST/api/v1/connect-hub/whatsapp/webhook
uuidstring
UUID koji vraća POST /whatsapp/otp
status"Success" | "Failed"
Ishod isporuke WhatsApp-a
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"
  }'

Telegram OTP

Prijavite isporuku Telegram poruke. Koristite POST /check-verification-status za validaciju koda na serverskoj strani — pogledajte Telegram OTP brzi početak za kompletan tok.

POST/api/v1/connect-hub/telegram/webhook
idstring
UUID koji vraća POST /telegram
status"Success" | "Failed"
Ishod isporuke Telegram-a
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"
  }'

Dolazni Telegram Gateway

Kada prosledite callback_url u svom Telegram zahtevu za slanje, Telegram Gateway će slati POST događaje o statusu verifikacije direktno na taj URL. Za razliku od drugih kanala, vi ste primalac — i Telegram potpisuje svaki zahtev sa HMAC-SHA256.

Zaglavlja potpisa
X-Request-TimestampUnix epoha u sekundama (ceo broj). Odbijte ako je |sada − timestamp| > 300.
X-Request-SignatureHeksadecimalno kodiran HMAC-SHA256. Verifikujte poređenjem bezbednim od vremenskih napada.
Algoritam potpisivanja: secret = SHA256(access_token) · data = "{timestamp}\n{rawBody}" · sig = HMAC-SHA256(secret, data)
Primer payload-a događaja
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 za verifikaciju potpisa
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 });
});

Uvek parsirajte telo nakon verifikacije potpisa, i to iz sirovog bajt bafera — a ne iz već parsiranog JSON objekta. Ponovna serijalizacija JSON-a može promeniti redosled bajtova i pokvariti HMAC.