Webhooks
Les webhooks poussent les événements d'EncryptInvoice 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 |