Aller au contenu
Sur cette page

Webhooks

Les webhooks poussent les événements d'Kworia vers vos systèmes, sans polling. Les abonnements se gèrent entièrement via l'API — voir la section WebhookSubscription de la référence.

S'abonner

curl -X POST "https://kworia.com/api/v1/webhooks" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/encryptinvoice",
    "events": ["invoice.paid", "invoice.overdue"],
    "secret": "votre-secret-de-signature"
  }'

Si vous omettez secret, un secret est généré et renvoyé une seule fois — conservez-le ; il signe chaque livraison de webhook.

Événements disponibles

GET /api/v1/webhooks/events renvoie le catalogue à jour. Actuellement :

Événement Déclenché quand
invoice.created / invoice.updated Une facture est créée / modifiée
invoice.sent Une facture est transmise au client
invoice.paid Une facture est intégralement payée
invoice.overdue Une facture dépasse son échéance impayée
quote.created Un devis est créé
quote.accepted / quote.rejected Un client accepte / refuse un devis
expense.created Une dépense est enregistrée
customer.created Un client est créé
einvoice.sent / einvoice.delivered / einvoice.failed Cycle de vie sur le réseau de facturation électronique

Vérifier les livraisons

Chaque livraison est un POST vers votre URL avec l'en-tête de signature :

X-Webhook-Signature: <HMAC-SHA256 hexadécimal du corps brut, clé = votre secret>

Vérifiez avant de faire confiance au contenu :

$expected = hash_hmac('sha256', $rawBody, $secret);
abort_unless(hash_equals($expected, $request->header('X-Webhook-Signature')), 401);

Répondez 2xx rapidement (faites le vrai travail de façon asynchrone). Les réponses non-2xx sont consignées dans le journal des livraisons.

Tester et surveiller

Point de terminaison Usage
POST /api/v1/webhooks/{id}/test Envoie une charge de test signée vers votre URL
GET /api/v1/webhooks/{id}/logs Livraisons récentes avec codes de statut et réponses