Webhooks

Les webhooks permettent à votre application de recevoir des callbacks HTTP en temps réel lorsque des événements se produisent dans votre organisation Gäld. Quand un événement est déclenché, Gäld envoie une requête POST à chaque URL de webhook enregistrée.

Configurer un webhook

Créez un webhook via l'API :

curl -X POST https://app.gaeld.ch/api/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://votre-app.com/webhooks/gaeld",
    "events": ["invoice.created", "invoice.finalized", "customer.created"],
    "is_active": true
  }'

La réponse inclut un secret — conservez-le en sécurité, vous en aurez besoin pour vérifier les signatures.

Événements

Événement	Se déclenche quand
invoice.created	Une nouvelle facture est créée
invoice.updated	Une facture est modifiée
invoice.deleted	Une facture est supprimée
invoice.finalized	Une facture est finalisée (verrouillée)
invoice.payment_recorded	Un paiement est enregistré sur une facture
customer.created	Un nouveau client est créé
customer.updated	Un client est modifié
customer.deleted	Un client est supprimé
expense.created	Une nouvelle dépense est créée
expense.updated	Une dépense est modifiée
expense.deleted	Une dépense est supprimée
expense.approved	Une dépense est approuvée

Utilisez GET /api/v1/meta/webhook-events pour récupérer cette liste programmatiquement.

Format du payload

Chaque livraison de webhook envoie une requête JSON POST :

{
  "event": "invoice.finalized",
  "timestamp": "2025-06-01T12:00:00Z",
  "data": {
    "id": "uuid",
    "number": "INV-2025-042",
    "status": "finalized",
    "customer": { "id": "uuid", "name": "ACME GmbH" },
    "total": "1081.00",
    "currency": "CHF"
  }
}

Le champ data contient la représentation complète de la ressource (même format que l'endpoint API correspondant).

En-têtes de la requête

En-tête	Description
Content-Type	application/json
X-Webhook-Signature	Digest hexadécimal HMAC-SHA256 du corps de la requête
X-Webhook-Event	Nom de l'événement (ex. invoice.created)
X-Webhook-Id	Identifiant unique de la livraison
User-Agent	Gaeld-Webhook/1.0

Vérification de la signature

Chaque requête webhook est signée avec HMAC-SHA256 et le secret du webhook. Vérifiez toujours la signature avant de traiter le payload.

PHP

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$computed = hash_hmac('sha256', $payload, $webhookSecret);

if (! hash_equals($computed, $signature)) {
    http_response_code(400);
    exit('Signature invalide');
}

$event = json_decode($payload, true);
// Traiter $event

Node.js

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  );
}

Python

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    computed = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(computed, signature)

Livraison & Tentatives

Propriété	Valeur
Timeout HTTP	10 secondes
Tentatives max	3
Intervalle de réessai	30 secondes, 5 minutes, 1 heure
Réponse attendue	Tout code de statut 2xx

Si votre endpoint retourne un code non-2xx ou expire, Gäld réessaie avec un backoff exponentiel. Après 3 échecs, la livraison est marquée comme échouée.

Gestion des webhooks

Action	Méthode	Endpoint
Lister tous	GET	/api/v1/webhooks
Voir les détails	GET	/api/v1/webhooks/{id}
Créer	POST	/api/v1/webhooks
Modifier	PUT	/api/v1/webhooks/{id}
Supprimer	DELETE	/api/v1/webhooks/{id}
Régénérer le secret	POST	/api/v1/webhooks/{id}/regenerate-secret

Rotation du secret

Après avoir appelé regenerate-secret, mettez à jour votre application avec le nouveau secret immédiatement. L'ancien secret est invalidé.

Bonnes pratiques

• Vérifiez toujours les signatures — ne faites jamais confiance au payload sans vérifier la signature HMAC
• Répondez rapidement — retournez 200 immédiatement et traitez l'événement de manière asynchrone
• Gérez les doublons — utilisez l'en-tête X-Webhook-Id pour dédupliquer
• Utilisez HTTPS — les URLs de webhook doivent utiliser HTTPS en production
• Surveillez les échecs — vérifiez périodiquement le statut des livraisons