Référence

Webhooks

Signalez les résultats de vérification à Novauth afin que vos enregistrements de session restent exacts. Chaque canal expose un endpoint webhook dédié que votre serveur appelle après avoir observé le résultat.

Fonctionnement

Novauth n'envoie pas d'événements à votre serveur. Au lieu de cela, votre backend observe le résultat de la vérification (via le SDK mobile, votre propre logique applicative ou un sondage de vérification de statut) puis envoie le résultat en POST à l'endpoint webhook du Connect Hub.

1
Initier
Votre serveur démarre une vérification via l'API du canal.
2
Action de l'utilisateur
L'utilisateur reçoit l'OTP et agit en conséquence (appel, SMS, message d'application).
3
Observer le résultat
Votre SDK mobile ou logique applicative détecte le succès ou l'échec.
4
Signaler le résultat
Votre serveur envoie uuid + status en POST à l'endpoint webhook.

Tous les endpoints webhook nécessitent le même en-tête x-api-key utilisé pour les requêtes API standard. Retournez HTTP 200 pour accuser réception.

Verify Call

Après que votre SDK mobile a lu l'ID d'appelant entrant, signalez si les chiffres correspondaient à l'appelant attendu.

POST/api/v1/connect-hub/call/flash/webhook
uuidstring
UUID retourné par POST /call/flash
status"Success" | "Failed" | "Incomplete" | "WrongNumber"
Résultat de l'appel observé
Charge utile
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
Exemple — envoyer le résultat
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

Une fois que votre serveur confirme que l'utilisateur a saisi le bon code OTP, signalez le statut de livraison à Novauth.

POST/api/v1/connect-hub/sms/webhook
idstring
messageId retourné par POST /sms
status"delivered" | "sent" | "failed" | "undelivered"
Statut de livraison SMS du DLR opérateur
Charge utile
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

Signalez le résultat de livraison de l'OTP WhatsApp. Seuls deux statuts sont possibles.

POST/api/v1/connect-hub/whatsapp/webhook
uuidstring
UUID retourné par POST /whatsapp/otp
status"Success" | "Failed"
Résultat de livraison 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

Signalez la livraison du message Telegram. Utilisez POST /check-verification-status pour la validation du code côté serveur — consultez le démarrage rapide OTP Telegram pour le flux complet.

POST/api/v1/connect-hub/telegram/webhook
idstring
UUID retourné par POST /telegram
status"Success" | "Failed"
Résultat de livraison 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"
  }'

Telegram Gateway entrant

Lorsque vous transmettez un callback_url dans votre requête d'envoi Telegram, le Gateway de Telegram enverra des événements de statut de vérification directement en POST à cette URL. Contrairement aux autres canaux, c'est vous qui êtes le récepteur — et Telegram signe chaque requête avec HMAC-SHA256.

En-têtes de signature
X-Request-TimestampSecondes d'époque Unix (entier). Rejetez si |now − timestamp| > 300.
X-Request-SignatureHMAC-SHA256 encodé en hexadécimal. Vérifiez avec une comparaison à temps constant.
Algorithme de signature : secret = SHA256(access_token) · data = "{timestamp}\n{rawBody}" · sig = HMAC-SHA256(secret, data)
Exemple de charge utile d'événement
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
Gestionnaire de vérification de signature
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 });
});

Analysez toujours le corps après la vérification de la signature, et analysez-le depuis le tampon d'octets bruts — pas depuis un objet JSON pré-analysé. La re-sérialisation JSON peut modifier l'ordre des octets et invalider le HMAC.