Referenz

Webhooks

Melde Verifizierungsergebnisse an Novauth zurück, damit deine Sitzungsdatensätze aktuell bleiben. Jeder Kanal stellt einen dedizierten Webhook-Endpunkt bereit, den dein Server nach Beobachtung des Ergebnisses aufruft.

So funktioniert es

Novauth sendet keine Ereignisse an deinen Server. Stattdessen beobachtet dein Backend das Verifizierungsergebnis (über das mobile SDK, deine eigene App-Logik oder einen Statusabfrage-Poll) und sendet das Ergebnis dann per POST an den Connect Hub Webhook-Endpunkt zurück.

1
Einleiten
Dein Server startet eine Verifizierung über die Kanal-API.
2
Nutzeraktion
Nutzer empfängt den OTP und handelt (Anruf, SMS, App-Nachricht).
3
Ergebnis beobachten
Dein mobiles SDK oder deine App-Logik erkennt Erfolg oder Misserfolg.
4
Ergebnis melden
Dein Server sendet uuid + Status per POST an den Webhook-Endpunkt.

Alle Webhook-Endpunkte erfordern denselben x-api-key-Header wie reguläre API-Anfragen. HTTP 200 zurückgeben zur Bestätigung.

Verify Call

Nachdem dein mobiles SDK die eingehende Anrufer-ID gelesen hat, melde, ob die Ziffern mit der erwarteten Anrufer-ID übereinstimmen.

POST/api/v1/connect-hub/call/flash/webhook
uuidstring
UUID zurückgegeben von POST /call/flash
status"Success" | "Failed" | "Incomplete" | "WrongNumber"
Beobachtetes Anrufergebnis
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
Beispiel — Ergebnis senden
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

Sobald dein Server bestätigt hat, dass der Nutzer den richtigen OTP-Code eingegeben hat, melde den Zustellstatus an Novauth zurück.

POST/api/v1/connect-hub/sms/webhook
idstring
messageId zurückgegeben von POST /sms
status"delivered" | "sent" | "failed" | "undelivered"
SMS-Zustellstatus vom Carrier-DLR
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

WhatsApp-OTP-Zustellergebnis melden. Nur zwei Statuswerte sind möglich.

POST/api/v1/connect-hub/whatsapp/webhook
uuidstring
UUID zurückgegeben von POST /whatsapp/otp
status"Success" | "Failed"
WhatsApp-Zustellergebnis
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

Telegram-Nachrichtenzustellung melden. POST /check-verification-status für serverseitige Code-Validierung verwenden – den vollständigen Ablauf findest du im Telegram-OTP-Schnellstart.

POST/api/v1/connect-hub/telegram/webhook
idstring
UUID zurückgegeben von POST /telegram
status"Success" | "Failed"
Telegram-Zustellergebnis
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"
  }'

Telegram Gateway eingehend

Wenn du eine callback_url in deiner Telegram-Sendeanfrage angibst, sendet das Gateway von Telegram Verifizierungsstatusereignisse per POST direkt an diese URL. Anders als bei den anderen Kanälen bist du der Empfänger – und Telegram signiert jede Anfrage mit HMAC-SHA256.

Signatur-Header
X-Request-TimestampUnix-Epoch in Sekunden (Integer). Ablehnen, wenn |jetzt − timestamp| > 300.
X-Request-SignatureHex-kodierter HMAC-SHA256. Mit zeitkonstantem Vergleich prüfen.
Signierungsalgorithmus: secret = SHA256(access_token) · data = "{timestamp}\n{rawBody}" · sig = HMAC-SHA256(secret, data)
Beispiel-Ereignis-Payload
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
Signaturprüfungs-Handler
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 });
});

Den Body immer nach der Signaturprüfung parsen und aus dem rohen Byte-Buffer – nicht aus einem vorher geparsten JSON-Objekt. JSON-Re-Serialisierung kann die Byte-Reihenfolge verändern und den HMAC brechen.