Organization IA Sources de recette · paquets 0.5.1

Références · Édition du 14 novembre 2026

Webhooks sortants

Les webhooks notifient un système externe après un événement de l’organisation. Ils sont distincts du webhook Stripe entrant. Leur gestion exige un compte administrateur et le module Studio.

Configurer

Dans Studio, créer un webhook avec une URL publique HTTPS et les événements voulus. Le code limite à dix webhooks par organisation. Le secret complet n’est présenté qu’à la création. Tester l’adresse depuis l’action de test et consulter le dernier résultat ; supprimer le webhook pour arrêter ses livraisons suivantes.

ÉvénementDéclencheur
document.sentDocument envoyé
document.paidFacture soldée
client.createdClient créé
task.createdTâche créée
task.doneTâche terminée
member.createdPersonne ajoutée

Contrat de livraison

POST JSON contient event, data et created. En-têtes : Content-Type: application/json, X-Orgia-Event et X-Orgia-Signature. La signature a la forme t=horodatage,v1=empreinte, HMAC SHA-256 sur les octets de l’horodatage, un point et le corps brut. Le secret est celui de ce webhook.

Le destinataire doit vérifier la signature sur les octets reçus, refuser un horodatage trop ancien et rendre ses traitements idempotents. Aucun identifiant d’événement durable n’est ajouté par ce contrat.

Exemple de vérification côté destinataire

Cette fonction vérifie la signature ; l’intégration HTTP et le stockage d’anti-rejeu relèvent du système destinataire. Ne pas réencoder le JSON avant vérification.

import hashlib, hmac, time

def signature_valide(header, body, secret):
    try:
        fields = dict(part.split('=', 1) for part in header.split(','))
        stamp = int(fields['t'])
        if abs(time.time() - stamp) > 300:
            return False
        signed = str(stamp).encode() + b'.' + body
        expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
        return hmac.compare_digest(expected, fields['v1'])
    except (ValueError, KeyError, TypeError):
        return False

Limites opérationnelles

Le délai réseau est de cinq secondes. Les redirections et adresses internes sont refusées par défaut ; ne pas affaiblir ces protections pour une intégration publique. Les livraisons automatiques sont désactivées avec ORGIA_SCHEDULER=0. Le test manuel reste une action explicite.

L’envoi s’effectue dans un thread en arrière-plan ; le dernier statut est conservé. Il n’existe pas ici de file durable, de reprise garantie après redémarrage ni de stratégie automatique de nouvelles tentatives. Pour une synchronisation fiable, prévoir rapprochement périodique autorisé avec l’API et contrôle des événements manquants.

Documentation préparée pour publication. Logiciel et accès web en recette privée ; aucun accès public ouvert par ce portail.