Referenca

Webhooks

Prijavljujte ishode verifikacije natrag Novauthu kako bi zapisi vaših sesija ostali točni. Svaki kanal izlaže namjenski webhook endpoint koji vaš poslužitelj poziva nakon što uoči rezultat.

Kako radi

Novauth ne šalje događaje vašem poslužitelju. Umjesto toga, vaš backend uočava ishod verifikacije (preko mobilnog SDK-a, vlastite logike aplikacije ili provjere statusa) i zatim POST-a rezultat natrag na Connect Hub webhook endpoint.

1
Pokretanje
Vaš poslužitelj pokreće verifikaciju preko API-ja kanala.
2
Radnja korisnika
Korisnik prima OTP i postupa po njemu (poziv, SMS, poruka u aplikaciji).
3
Uočavanje ishoda
Vaš mobilni SDK ili logika aplikacije detektira uspjeh ili neuspjeh.
4
Prijavljivanje rezultata
Vaš poslužitelj POST-a uuid + status na webhook endpoint.

Svi webhook endpointi zahtijevaju isto x-api-key zaglavlje koje se koristi za redovne API zahtjeve. Vratite HTTP 200 kao potvrdu primitka.

Verify Call

Nakon što vaš mobilni SDK pročita dolazni ID pozivatelja, prijavite jesu li se znamenke poklopile s očekivanim pozivateljem.

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
Primjer — 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š poslužitelj potvrdi da je korisnik unio ispravan OTP kod, prijavite status isporuke natrag Novauthu.

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 operatora
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 WhatsAppa
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 poslužiteljskoj strani — pogledajte Telegram OTP brzi početak za kompletan tijek.

POST/api/v1/connect-hub/telegram/webhook
idstring
UUID koji vraća POST /telegram
status"Success" | "Failed"
Ishod isporuke Telegrama
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 proslijedite callback_url u svom Telegram zahtjevu za slanje, Telegram Gateway slat će POST događaje o statusu verifikacije izravno na taj URL. Za razliku od drugih kanala, vi ste primatelj — i Telegram potpisuje svaki zahtjev s HMAC-SHA256.

Zaglavlja potpisa
X-Request-TimestampUnix epoha u sekundama (cijeli broj). Odbijte ako je |sada − timestamp| > 300.
X-Request-SignatureHeksadecimalno kodiran HMAC-SHA256. Verificirajte usporedbom sigurnom od vremenskih napada.
Algoritam potpisivanja: secret = SHA256(access_token) · data = "{timestamp}\n{rawBody}" · sig = HMAC-SHA256(secret, data)
Primjer payloada 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 });
});

Uvijek parsirajte tijelo nakon verifikacije potpisa, i to iz sirovog bajt buffera — a ne iz već parsiranog JSON objekta. Ponovna serijalizacija JSON-a može promijeniti redoslijed bajtova i pokvariti HMAC.