Webhooks

Recevez des notifications en temps réel lorsque vos validations bancaires sont terminées.

Fonctionnalité Pack Business

Les webhooks sont disponibles exclusivement avec le Pack Business. Ils vous permettent de recevoir des notifications automatiques sans interroger l'API en continu (polling).

Comment ça fonctionne

Les webhooks permettent à BankValidor d'envoyer des notifications HTTP POST à votre serveur lorsqu'un événement se produit.

Enregistrez votre URL

Configurez l'URL de votre endpoint via l'API. Spécifiez les événements auxquels vous souhaitez souscrire.

Réception automatique

À chaque événement correspondant, BankValidor envoie un POST HTTP à votre URL avec les détails de la validation au format JSON.

Politique de retry

Si votre serveur ne répond pas avec un code 2xx, BankValidor réessaie automatiquement avec un backoff exponentiel (jusqu'à 3 tentatives).

Événements disponibles

BankValidor émet les événements suivants. Sélectionnez ceux auxquels vous souhaitez souscrire lors de la configuration de votre webhook.

Événement	Description
validation.completed	Émis lorsqu'une validation unitaire (US, UK, SWIFT, IBAN) est terminée avec succès.
validation.failed	Émis lorsqu'une validation unitaire échoue (erreur de format, registre non trouvé).
bulk.completed	Émis lorsque le traitement d'un fichier CSV en masse est terminé. Contient le lien de téléchargement du fichier résultat.
bulk.failed	Émis lorsque le traitement d'un fichier CSV échoue (erreur de format, timeout, fichier corrompu).

Format du payload

Chaque notification webhook contient un payload JSON structuré avec les informations de l'événement et les données de validation.

Exemple de payload (validation.completed)

{
  "event_id": "evt_a1b2c3d4e5f6",
  "event_type": "validation.completed",
  "timestamp": "2025-01-15T14:30:00Z",
  "api_version": "v1",
  "data": {
    "validation_id": "val_x9y8z7w6",
    "type": "swift",
    "input": "DEUTDEFF500",
    "status": "VALID",
    "confidence": "HIGH",
    "bank_info": {
      "name": "Deutsche Bank AG",
      "city": "Frankfurt am Main",
      "country": "DE"
    },
    "validation_details": {
      "syntax": true,
      "checksum": true,
      "registry_match": true
    }
  }
}

Champs du payload

event_idIdentifiant unique de l'événement (pour la déduplication / idempotence)
event_typeType d'événement (validation.completed, validation.failed, bulk.completed, bulk.failed)
timestampHorodatage ISO 8601 de l'événement
api_versionVersion de l'API utilisée (actuellement v1)
dataObjet contenant les détails de la validation (type, input, status, confidence, bank_info)

Sécurité

Chaque notification webhook est signée avec votre secret pour garantir l'authenticité et l'intégrité du payload.

En-tête de signature

BankValidor signe chaque payload avec HMAC-SHA256 en utilisant votre secret webhook. Vérifiez cette signature côté serveur pour vous assurer que la notification provient bien de BankValidor.

X-Webhook-Signature: sha256=a1b2c3d4e5f6...

Python

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    """Verify the HMAC-SHA256 signature of a webhook payload."""
    expected = hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256
    ).hexdigest()
    received = signature.replace("sha256=", "")
    return hmac.compare_digest(expected, received)

# Usage in your endpoint:
# signature = request.headers["X-Webhook-Signature"]
# is_valid = verify_webhook_signature(request.body, signature, WEBHOOK_SECRET)

Node.js

const crypto = require("crypto");

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload, "utf-8")
    .digest("hex");
  const received = signature.replace("sha256=", "");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex")
  );
}

// Usage in your Express handler:
// const signature = req.headers["x-webhook-signature"];
// const isValid = verifyWebhookSignature(req.rawBody, signature, WEBHOOK_SECRET);

Configuration

Gérez vos webhooks via l'API REST. Vous pouvez créer, lister et supprimer des webhooks.

Enregistrer un webhook

POST /api/v1/webhooks

curl -X POST https://bankvalidor.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/bank-validator",
    "events": ["validation.completed", "validation.failed"],
    "secret": "your_webhook_secret"
  }'

# Response:
{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/bank-validator",
  "events": ["validation.completed", "validation.failed"],
  "active": true,
  "created_at": "2025-01-15T10:00:00Z"
}

Lister les webhooks

GET /api/v1/webhooks

curl https://bankvalidor.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
{
  "webhooks": [
    {
      "id": "wh_abc123",
      "url": "https://your-app.com/webhooks/bank-validator",
      "events": ["validation.completed", "validation.failed"],
      "active": true,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Supprimer un webhook

DELETE /api/v1/webhooks/:id

curl -X DELETE https://bankvalidor.com/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
{
  "deleted": true,
  "id": "wh_abc123"
}

Politique de retry

En cas d'échec de livraison (timeout, erreur HTTP 5xx), BankValidor réessaie automatiquement avec un délai croissant.

Tentative	Délai	Timeout
1ère tentative	Immédiat	30s
2ème tentative	5 minutes	30s
3ème tentative	30 minutes	30s

Après 3 échecs

Si les 3 tentatives échouent, l'événement est marqué comme non délivré. Vous pouvez consulter les événements en échec via l'endpoint GET /api/v1/webhooks/failures et les rejouer manuellement.

Bonnes pratiques

Répondez immédiatement avec un 200

Votre endpoint doit retourner un code HTTP 200 le plus rapidement possible. Tout traitement lourd doit être effectué de manière asynchrone après la réponse.

Traitez de manière asynchrone

Enregistrez le payload et traitez-le en arrière-plan. Cela évite les timeouts et garantit que BankValidor reçoit votre accusé de réception.

Implémentez l'idempotence

Utilisez l'event_id pour détecter et ignorer les doublons. En cas de retry, le même événement peut être envoyé plusieurs fois.

Python (FastAPI)

from fastapi import FastAPI, Request, BackgroundTasks
from fastapi.responses import JSONResponse

app = FastAPI()

@app.post("/webhooks/bank-validator")
async def handle_webhook(request: Request, bg: BackgroundTasks):
    # 1. Respond 200 immediately
    payload = await request.json()
    event_id = payload["event_id"]

    # 2. Check idempotency (skip if already processed)
    if await is_already_processed(event_id):
        return JSONResponse({"status": "already_processed"})

    # 3. Process asynchronously
    bg.add_task(process_validation_event, payload)

    return JSONResponse({"status": "accepted"})

Node.js (Express)

const express = require("express");
const app = express();

app.post("/webhooks/bank-validator", express.json(), async (req, res) => {
  const { event_id } = req.body;

  // 1. Respond 200 immediately
  res.status(200).json({ status: "accepted" });

  // 2. Check idempotency (skip if already processed)
  const alreadyProcessed = await checkIfProcessed(event_id);
  if (alreadyProcessed) return;

  // 3. Process asynchronously
  processValidationEvent(req.body).catch(console.error);
});

Documentation associée

API REST

Documentation complète des endpoints de validation unitaire.

Consulter →

Validation CSV en masse

Validez des milliers de coordonnées bancaires en une seule requête.

Consulter →

BankValidor — Webhooks