Configuration des Webhooks

Les webhooks vous permettent de recevoir des notifications en temps réel lorsque des événements se produisent dans votre espace de travail Subnoto. Ce guide vous aidera à configurer des webhooks pour intégrer avec vos systèmes.

Vue d’ensemble

Les webhooks sont des requêtes HTTP POST envoyées à votre URL spécifiée lorsque des événements spécifiques se produisent dans Subnoto. Ils vous permettent de :

• Mettre à jour automatiquement vos systèmes lorsque des enveloppes sont signées
• Déclencher des workflows lorsque des documents sont complétés
• Maintenir la synchronisation des systèmes externes avec Subnoto

Événements Disponibles

Subnoto supporte les événements de webhook suivants :

ENVELOPE_SIGNED

Déclenché lorsqu’un destinataire signe une enveloppe. Cet événement est déclenché à chaque fois qu’un destinataire complète sa signature.

ENVELOPE_COMPLETED

Déclenché lorsqu’une enveloppe est entièrement complétée et que toutes les signatures requises ont été collectées. Cet événement est déclenché une fois par complétion d’enveloppe.

Créer un Webhook

1. Connectez-vous à votre espace de travail Subnoto sur app.subnoto.com
2. Naviguez vers Paramètres → Webhooks
3. Cliquez sur “Créer un webhook”
4. Remplissez la configuration du webhook (voir Options de Configuration ci-dessous)
5. Cliquez sur “Ajouter un webhook”

Options de Configuration

URL de Payload

L’endpoint HTTPS où les payloads de webhook seront envoyés. Cela doit être une URL publiquement accessible.

Exemple : https://api.exemple.com/webhooks/subnoto

Type de Contenu

Choisissez comment le payload du webhook doit être formaté :

• application/json : Payload envoyé en JSON dans le corps de la requête
• application/x-www-form-urlencoded : Payload envoyé sous forme de données encodées en formulaire

Secret (Optionnel)

Une clé secrète utilisée pour générer des signatures HMAC pour la vérification des webhooks. Si fournie, la requête de webhook inclura un en-tête de signature que vous pouvez utiliser pour vérifier l’authenticité de la requête.

Meilleure Pratique de Sécurité : Utilisez toujours un secret pour vérifier l’authenticité du webhook et empêcher les requêtes non autorisées.

Vérification SSL

Par défaut, Subnoto vérifie les certificats SSL lors de la livraison des payloads de webhook. Désactiver la vérification SSL n’est pas recommandé car cela peut exposer votre endpoint de webhook à des risques de sécurité.

Événements

Vous pouvez choisir de recevoir :

• Tous les événements : Recevez des notifications pour ENVELOPE_SIGNED et ENVELOPE_COMPLETED
• Événements individuels : Sélectionnez des événements spécifiques pour lesquels vous souhaitez être notifié

Espaces de Travail

Vous pouvez filtrer les webhooks vers des espaces de travail spécifiques :

• Tous les espaces de travail : Recevez des événements de tous les espaces de travail de votre équipe
• Espaces de travail spécifiques : Sélectionnez les espaces de travail qui doivent déclencher ce webhook

Statut Actif

Lorsqu’il est activé, le webhook recevra des notifications d’événements. Lorsqu’il est désactivé, le webhook est inactif et ne sera pas déclenché.

Format du Payload Webhook

Payload JSON Standard

Pour les endpoints non-Discord/Slack avec le type de contenu application/json :

{
    "eventUuid": "0f29a0a2-3a6f-44a4-b2a2-5d7b3f1b1f9b",
    "eventType": "ENVELOPE_SIGNED",
    "eventTime": 1704067200000,
    "webhookUuid": "webhook-uuid",
    "teamUuid": "team-uuid",
    "data": {
        "workspaceUuid": "workspace-uuid",
        "envelopeUuid": "envelope-uuid",
        "recipientEmail": "[email protected]",
        "recipientName": "Jean Dupont"
    }
}

Exemple d’événement ENVELOPE_COMPLETED :

{
    "eventUuid": "f5a6c2d3-2e1b-4c7a-92ab-5e8f2d1c0b9a",
    "eventType": "ENVELOPE_COMPLETED",
    "eventTime": 1704067200000,
    "webhookUuid": "webhook-uuid",
    "teamUuid": "team-uuid",
    "data": {
        "workspaceUuid": "workspace-uuid",
        "envelopeUuid": "envelope-uuid",
        "documentUuid": "document-uuid",
        "finalRevisionVersion": 1
    }
}

Payload Encodé en Formulaire

Pour le type de contenu application/x-www-form-urlencoded, le payload est envoyé comme un champ de formulaire :

payload={"eventUuid":"...","eventType":"ENVELOPE_SIGNED","eventTime":1704067200000,"webhookUuid":"...","teamUuid":"...","data":{"workspaceUuid":"...","envelopeUuid":"...","recipientEmail":"...","recipientName":"..."}}

Intégration Discord et Slack

Subnoto détecte automatiquement les URLs de webhook Discord et Slack et formate le payload selon leurs exigences API respectives. Pour ces plateformes, le format de payload est optimisé pour leurs systèmes de notification. La structure ci-dessus s’applique uniquement aux payloads JSON/form par défaut.

En-têtes Webhook

Toutes les requêtes de webhook incluent les en-têtes suivants :

X-Webhook-Id

L’identifiant unique du webhook qui a envoyé la requête.

X-Webhook-Id: webhook-uuid

X-Webhook-Signature (Lorsqu’un Secret est Configuré)

La signature HMAC pour la vérification du webhook. Incluse uniquement lorsqu’un secret est configuré.

X-Webhook-Signature: t=1704067200000,v1=<signature>

Le format de signature est :

• t : Timestamp Unix en millisecondes
• v1 : Signature HMAC SHA256

Vérifier les Signatures Webhook

Pour vérifier qu’une requête de webhook est authentique et provient de Subnoto, vous devez vérifier la signature HMAC :

import crypto from "crypto";

function verifyWebhookSignature(signature, timestamp, body, secret) {
    // Parser l'en-tête de signature : t=<timestamp>,v1=<signature>
    const match = signature.match(/t=(\d+),v1=(.+)/);
    if (!match) return false;

    const [, sigTimestamp, sigValue] = match;

    // Vérifier que le timestamp est récent (optionnel : empêcher les attaques de rejeu)
    const now = Date.now();
    const requestTime = parseInt(sigTimestamp);
    if (Math.abs(now - requestTime) > 300000) {
        // Tolérance de 5 minutes
        return false;
    }

    // Recréer la signature
    const expectedSignature = crypto.createHmac("sha256", secret).update(`t:${sigTimestamp}:${body}`).digest("hex");

    return crypto.timingSafeEqual(Buffer.from(sigValue), Buffer.from(expectedSignature));
}

Exemple Python

import hmac
import hashlib
import time

def verify_webhook_signature(signature_header, body, secret):
    # Parser l'en-tête de signature : t=<timestamp>,v1=<signature>
    try:
        parts = signature_header.split(',')
        timestamp = parts[0].split('=')[1]
        sig_value = parts[1].split('=')[1]
    except (IndexError, ValueError):
        return False

    # Vérifier que le timestamp est récent (optionnel : empêcher les attaques de rejeu)
    now = int(time.time() * 1000)
    request_time = int(timestamp)
    if abs(now - request_time) > 300000:  # Tolérance de 5 minutes
        return False

    # Recréer la signature
    message = f't:{timestamp}:{body}'
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(sig_value, expected_signature)

Tester les Webhooks

Vous pouvez tester votre configuration de webhook directement depuis l’interface web :

1. Naviguez vers Paramètres → Webhooks
2. Trouvez le webhook que vous souhaitez tester
3. Cliquez sur le menu d’actions (trois points)
4. Sélectionnez “Tester le webhook”

Cela enverra un payload de test à votre URL de webhook avec des données d’exemple, vous permettant de vérifier que votre endpoint reçoit et traite correctement les requêtes de webhook.

Dépannage

Webhook Non Reçu

• Vérifiez que le webhook est actif dans les paramètres Subnoto
• Vérifiez que votre URL d’endpoint est publiquement accessible
• Assurez-vous que votre endpoint accepte les requêtes POST
• Vérifiez la validité du certificat SSL si la vérification SSL est activée
• Consultez les logs de votre serveur pour les requêtes entrantes

Signature Invalide

• Vérifiez que vous utilisez la bonne clé secrète
• Assurez-vous d’inclure le corps complet de la requête dans le calcul de signature
• Vérifiez que le timestamp dans l’en-tête de signature est récent
• Pour les payloads encodés en formulaire, vérifiez que vous utilisez les données de formulaire, pas JSON

Événement Ne Se Déclenche Pas

• Vérifiez que le type d’événement est inclus dans votre configuration de webhook
• Vérifiez que le filtre d’espace de travail correspond à l’espace de travail de l’événement
• Assurez-vous que le webhook est actif
• Vérifiez que le statut de l’enveloppe correspond au déclencheur d’événement attendu