Passer au contenu principal

​
Apercu

Les webhooks permettent a TXCloud d’envoyer des notifications en temps reel a votre serveur lorsque des evenements se produisent. Au lieu d’interroger notre API, vous recevez les mises a jour automatiquement.

​
Comment Fonctionnent les Webhooks

​
Configurer les Webhooks

​
Etape 1 : Creer un Endpoint Webhook

Creez un endpoint sur votre serveur pour recevoir les evenements webhook : 
// Exemple Express.js
app.post('/webhooks/txcloud', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-txcloud-signature'];
  const payload = req.body;

  // Verifier la signature
  if (!verifySignature(payload, signature, webhookSecret)) {
    return res.status(401).send('Signature invalide');
  }

  const event = JSON.parse(payload);

  // Gerer l'evenement
  switch (event.type) {
    case 'identity.verification.completed':
      handleVerificationCompleted(event.data);
      break;
    case 'fraud.signal.detected':
      handleFraudSignal(event.data);
      break;
    default:
      console.log(`Type d'evenement non gere: ${event.type}`);
  }

  res.status(200).send('OK');
});

​
Etape 2 : Enregistrer Votre Webhook

const webhook = await txcloud.developers.webhooks.create({
  url: 'https://votreapp.com/webhooks/txcloud',
  events: [
    'identity.verification.completed',
    'identity.verification.failed',
    'transaction.scored',
    'fraud.signal.detected'
  ],
  description: 'Webhook de production'
});

// Sauvegardez le secret pour la verification de signature
console.log('Secret Webhook:', webhook.secret);

​
Evenements Webhook

​
Evenements Identite

EvenementDescription
identity.verification.completedVerification terminee avec succes
identity.verification.failedVerification echouee
identity.session.expiredSession expiree avant completion

​
Evenements Fraude

EvenementDescription
fraud.signal.detectedSignal de fraude detecte
fraud.device.blockedAppareil ajoute a la liste de blocage
fraud.rule.triggeredRegle personnalisee declenchee

​
Evenements Transaction

EvenementDescription
transaction.scoredTransaction scoree
transaction.review_requiredRevision manuelle necessaire
transaction.fraud_detectedFraude confirmee

​
Evenements Credit

EvenementDescription
lending.assessment.completedEvaluation de credit terminee
lending.statement.analyzedAnalyse de releve bancaire complete
lending.monitor.alertAlerte de surveillance declenchee

​
Evenements Watchlist

EvenementDescription
watchlist.screening.completedFiltrage termine
watchlist.match.foundCorrespondance potentielle trouvee
watchlist.monitor.alertAlerte de surveillance continue

​
Payload d’Evenement

Tous les evenements webhook suivent cette structure : 
{
  "id": "evt_a1b2c3d4e5f6",
  "type": "identity.verification.completed",
  "created_at": "2025-01-15T10:30:00Z",
  "api_version": "2025-01-01",
  "data": {
    "id": "ver_xyz789",
    "status": "verified",
    "extracted_data": { ... },
    "checks": { ... }
  }
}
ChampTypeDescription
idstringID unique de l’evenement
typestringType d’evenement
created_atdatetimeDate de creation de l’evenement
api_versionstringVersion de l’API utilisee
dataobjectPayload specifique a l’evenement

​
Verification de Signature

Verifiez toujours les signatures webhook pour vous assurer que les evenements proviennent de TXCloud.
TXCloud signe tous les payloads webhook en utilisant HMAC-SHA256 : 
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const signatureBuffer = Buffer.from(signature, 'hex');
  const expectedBuffer = Buffer.from(expectedSignature, 'hex');

  return crypto.timingSafeEqual(signatureBuffer, expectedBuffer);
}
La signature est envoyee dans l’en-tete X-TXCloud-Signature : 
POST /webhooks/txcloud HTTP/1.1
Host: votreapp.com
Content-Type: application/json
X-TXCloud-Signature: a1b2c3d4e5f6...
X-TXCloud-Timestamp: 1705312800

{"id": "evt_abc123", ...}

​
Politique de Re-essai

Si votre endpoint ne repond pas avec un statut 2xx, TXCloud reessaiera :
TentativeDelai
1Immediat
21 minute
35 minutes
430 minutes
52 heures
612 heures
724 heures
Apres 7 tentatives echouees, le webhook est marque comme echoue et nous vous notifierons par email.
Retournez une reponse 2xx aussi rapidement que possible. Traitez les evenements de maniere asynchrone pour eviter les timeouts.

​
Bonnes Pratiques

Retournez une reponse 200 immediatement, puis traitez de maniere asynchrone :
app.post('/webhooks', (req, res) => {
  // Repondre immediatement
  res.status(200).send('OK');

  // Traiter de maniere asynchrone
  processEvent(req.body).catch(console.error);
});
Les evenements peuvent etre livres plus d’une fois. Utilisez l’id de l’evenement pour l’idempotence :
if (await eventAlreadyProcessed(event.id)) {
  return; // Ignorer le doublon
}
Pour les webhooks a haut volume, poussez les evenements vers une file :
  • Amazon SQS
  • Redis Queue
  • RabbitMQ
Verifiez le statut de livraison des webhooks dans votre tableau de bord. Les webhooks echoues sont journalises avec les details d’erreur.

​
Tester les Webhooks

​
Envoyer un Evenement de Test

// Envoyer un evenement de test a votre endpoint
await txcloud.developers.webhooks.test(webhookId, {
  event_type: 'identity.verification.completed'
});

​
Developpement Local

Utilisez un service de tunneling pour les tests locaux : 
# Avec ngrok
ngrok http 3000

# Votre endpoint local devient accessible a :
# https://abc123.ngrok.io/webhooks/txcloud

​
Logs Webhook

Visualisez les logs de livraison dans le tableau de bord ou via l’API : 
const logs = await txcloud.developers.webhooks.deliveries(webhookId, {
  limit: 20,
  status: 'failed'  // ou 'success'
});

logs.data.forEach(log => {
  console.log(`${log.event_type}: ${log.response_status} - ${log.created_at}`);
});

Tableau de Bord Webhooks

Visualisez et gerez les webhooks dans votre tableau de bord