Configurez vos endpoints webhook et vérifiez les livraisons de manière sécurisée.

Webhooks

Genuka Pay peut notifier votre backend sur les événements transaction, payout, KYC et company.

Headers requis

Les requêtes de gestion d’endpoints webhook doivent inclure :

X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE

Flux recommandé

Les webhooks doivent être gérés depuis le dashboard Genuka Pay, via la page Webhooks.

Ce flux permet à votre équipe :

de créer des endpoints

de choisir les événements

d’activer ou désactiver les endpoints

d’inspecter quelques métadonnées de livraison

de régénérer le secret

Utilisez l’API ci-dessous seulement pour l’automatisation ou l’outillage interne.

API de gestion

GET /api/v1/webhook-endpoints

POST /api/v1/webhook-endpoints

GET /api/v1/webhook-endpoints/{id}

PUT /api/v1/webhook-endpoints/{id}

DELETE /api/v1/webhook-endpoints/{id}

POST /api/v1/webhook-endpoints/{id}/regenerate-secret

Créer un endpoint

curl -X POST "{{BASE_URL}}/api/v1/webhook-endpoints" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend de production",
    "target_url": "https://merchant.example.com/webhooks/genuka",
    "events": [
      "transaction.success",
      "transaction.failed",
      "payout.success",
      "kyc.approved"
    ],
    "is_active": true
  }'

Événements disponibles

transaction.success

transaction.failed

transaction.processing

transaction.refunded

payout.success

payout.failed

payout.processing

payout.cancelled

kyc.submitted

kyc.approved

kyc.rejected

company.created

company.suspended

company.reactivated

Forme du payload

{
  "id": "01HW...",
  "event": "transaction.success",
  "timestamp": "2026-04-01T12:10:00Z",
  "data": {
    "transaction_id": "01HR...",
    "track_id": "TRX_01HR...",
    "status": "SUCCESS"
  }
}

Headers envoyés :

X-Webhook-Id

X-Webhook-Event

Vérification de signature

La livraison webhook utilise HMAC-SHA256 avec le secret de l’endpoint.

import crypto from "crypto";

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Rotation du secret

curl -X POST "{{BASE_URL}}/api/v1/webhook-endpoints/{id}/regenerate-secret" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE"

Le nouveau secret doit être stocké immédiatement.

Recommandations

retournez un 2xx rapidement

poussez le traitement lourd dans une queue

vérifiez la signature avant traitement

implémentez l’idempotence côté récepteur

Webhooks

On this page