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 :

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

Créer un Webhook

Connectez-vous à votre espace de travail Subnoto sur app.subnoto.com
Naviguez vers Paramètres → Webhooks
Cliquez sur “Créer un webhook”
Remplissez la configuration du webhook (voir Options de Configuration ci-dessous)
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 tous les événements (ENVELOPE_CREATED, ENVELOPE_SENT, ENVELOPE_OPENED, ENVELOPE_SIGNED, ENVELOPE_COMPLETED, ENVELOPE_DECLINED, ENVELOPE_CANCELED)
É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
    }
}

Exemple d’événement ENVELOPE_SENT (optionnel recipients dans data) :

{
    "eventType": "ENVELOPE_SENT",
    "data": {
        "workspaceUuid": "workspace-uuid",
        "envelopeUuid": "envelope-uuid",
        "recipients": [
            { "email": "[email protected]", "role": "signer", "order": 1 }
        ]
    }
}

Exemple d’événement ENVELOPE_DECLINED (optionnel reason, decliner dans data) :

{
    "eventType": "ENVELOPE_DECLINED",
    "data": {
        "workspaceUuid": "workspace-uuid",
        "envelopeUuid": "envelope-uuid",
        "reason": "Impossible de signer",
        "decliner": { "email": "[email protected]", "firstname": "Jane", "lastname": "Doe" }
    }
}

Exemple d’événement ENVELOPE_CANCELED (optionnel reason dans data) :

{
    "eventType": "ENVELOPE_CANCELED",
    "data": {
        "workspaceUuid": "workspace-uuid",
        "envelopeUuid": "envelope-uuid",
        "reason": "Plus nécessaire"
    }
}

Exemple d’événement ENVELOPE_CREATED :

{
    "eventUuid": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "eventType": "ENVELOPE_CREATED",
    "eventTime": 1704067200000,
    "webhookUuid": "webhook-uuid",
    "teamUuid": "team-uuid",
    "data": {
        "workspaceUuid": "workspace-uuid",
        "envelopeUuid": "envelope-uuid"
    }
}

Exemple d’événement ENVELOPE_OPENED (optionnel recipient dans data) :

{
    "eventUuid": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "eventType": "ENVELOPE_OPENED",
    "eventTime": 1704067200000,
    "webhookUuid": "webhook-uuid",
    "teamUuid": "team-uuid",
    "data": {
        "workspaceUuid": "workspace-uuid",
        "envelopeUuid": "envelope-uuid",
        "recipient": { "email": "[email protected]", "firstname": "Jane", "lastname": "Doe" }
    }
}

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 :

Naviguez vers Paramètres → Webhooks
Trouvez le webhook que vous souhaitez tester
Cliquez sur le menu d’actions (trois points)
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

Gérer les webhooks via l’API

Vous pouvez créer, lister, modifier et supprimer des webhooks avec une clé API d’équipe : guide Gérer les webhooks via l’API.