Documentation des événements Webhook SecuSign

Cette documentation liste tous les événements webhook disponibles dans le service SecuSign, avec leurs paramètres et descriptions.

📋 Table des matières

• Événements Signatory
• Événements Transaction
• Structure des payloads
• Authentification

Événements Signatory

Les événements liés aux signataires sont déclenchés lorsqu'un signataire est créé, modifié ou change de statut.

signatory.created

Description : Déclenché lors de la création d'un nouveau signataire dans une transaction.

Quand : Immédiatement après la création d'un signataire associé à une transaction.

Paramètres retournés :

Exemple de payload :

{
  "event": "signatory.created",
  "signatory_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transaction_uid": "f0e1d2c3-b4a5-9687-fedc-ba9876543210",
  "changed_fields": {
    "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe"
  },
  "document_fields": {}
}

signatory.updated

Description : Déclenché lors de la mise à jour des informations d'un signataire (hors changements de statut).

Quand : Lorsque des modifications sont apportées aux données du signataire (nom, email, etc.)

Paramètres retournés :

Exemple de payload :

{
  "event": "signatory.updated",
  "signatory_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transaction_uid": "f0e1d2c3-b4a5-9687-fedc-ba9876543210",
  "changed_fields": {
    "email": "[email protected]"
  },
  "document_fields": {
    "company_name": "ACME Corp",
    "position": "CEO"
  }
}

signatory.status.signed

Description : Déclenché lorsqu'un signataire a signé le document.

Quand : Immédiatement après qu'un signataire ait complété le processus de signature.

Paramètres retournés :

Exemple de payload :

{
  "event": "signatory.status.signed",
  "signatory_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transaction_uid": "f0e1d2c3-b4a5-9687-fedc-ba9876543210",
  "status": "signed",
  "date": "2026-04-15 14:30:45",
  "changed_fields": {
    "signed_date": "2026-04-15 14:30:45"
  },
  "document_fields": {
    "company_name": "ACME Corp",
    "position": "CEO",
    "birth_date": "1980-05-12"
  }
}

signatory.status.refused

Description : Déclenché lorsqu'un signataire a refusé de signer le document.

Quand : Immédiatement après qu'un signataire ait explicitement refusé de signer.

Paramètres retournés :

Exemple de payload :

{
  "event": "signatory.status.refused",
  "signatory_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transaction_uid": "f0e1d2c3-b4a5-9687-fedc-ba9876543210",
  "status": "refused",
  "date": "2026-04-15 11:20:15",
  "changed_fields": {
    "refused_date": "2026-04-15 11:20:15"
  },
  "document_fields": {}
}

Événements Transaction

Les événements liés aux transactions sont déclenchés lors des changements d'état du processus de signature.

transaction.created

Description : Déclenché lors de la création d'une nouvelle transaction de signature.

Quand : Immédiatement après la création d'une transaction (upload du document et configuration).

Paramètres retournés :

Exemple de payload :

{
  "event": "transaction.created",
  "transaction_uid": "f0e1d2c3-b4a5-9687-fedc-ba9876543210",
  "transaction_status": "created",
  "changed_fields": {
    "uid": "f0e1d2c3-b4a5-9687-fedc-ba9876543210",
    "name": "Contrat de service 2026",
    "status": "created"
  }
}

transaction.updated

Description : Déclenché lors de la mise à jour d'une transaction (hors changements de statut).

Quand : Lorsque des modifications sont apportées à la transaction (nom, paramètres, etc.)

Paramètres retournés :

Exemple de payload :

{
  "event": "transaction.updated",
  "transaction_uid": "f0e1d2c3-b4a5-9687-fedc-ba9876543210",
  "transaction_status": "created",
  "changed_fields": {
    "name": "Contrat de service 2026 - Modifié"
  }
}

transaction.status.sent

Description : Déclenché lorsqu'un signataire accède pour la première fois à la visualisation du document.

Quand : Dès qu'un signataire ouvre le lien de visualisation/signature du document (premier accès).

Paramètres retournés :

Exemple de payload :

{
  "event": "transaction.status.sent",
  "transaction_uid": "f0e1d2c3-b4a5-9687-fedc-ba9876543210",
  "transaction_status": "sent",
  "changed_fields": {
    "status": "sent",
    "sent_date": "2026-04-15 09:00:00"
  }
}

transaction.status.completed

Description : Déclenché lorsque tous les signataires ont signé le document ou lorsque le statut est forcé manuellement.

Quand :

• Immédiatement après que le dernier signataire requis ait complété sa signature
• Lorsqu'un administrateur force le passage au statut "completed" via un appel API

Paramètres retournés :

Exemple de payload :

{
  "event": "transaction.status.completed",
  "transaction_uid": "f0e1d2c3-b4a5-9687-fedc-ba9876543210",
  "transaction_status": "completed",
  "changed_fields": {
    "status": "completed",
    "completed_date": "2026-04-15 16:45:30"
  }
}

transaction.status.canceled / transaction.status.cancelled

Description : Déclenché lorsque la transaction a été annulée.

Quand : Lorsqu'un administrateur ou le créateur de la transaction l'annule manuellement.

⚠️ Note : Le nom de l'événement peut être canceled ou cancelled selon l'orthographe utilisée dans le système.

Paramètres retournés :

Exemple de payload :

{
  "event": "transaction.status.cancelled",
  "transaction_uid": "f0e1d2c3-b4a5-9687-fedc-ba9876543210",
  "transaction_status": "cancelled",
  "changed_fields": {
    "status": "cancelled",
    "cancel_date": "2026-04-15 12:00:00"
  }
}

transaction.status.expired

Description : Déclenché lorsque la transaction a expiré sans avoir été complétée.

Quand : Automatiquement lorsque le délai d'expiration (30 jours par défaut, configurable) est atteint sans que la transaction n'ait atteint le statut "completed".

Paramètres retournés :

Exemple de payload :

{
  "event": "transaction.status.expired",
  "transaction_uid": "f0e1d2c3-b4a5-9687-fedc-ba9876543210",
  "transaction_status": "expired",
  "changed_fields": {
    "status": "expired"
  }
}

Structure des payloads

Champs communs

Tous les webhooks incluent certains champs de base :

• event : Identifie le type d'événement
• UID : Identifiant unique (signatory_uid ou transaction_uid)
• changed_fields : Objet contenant uniquement les champs qui ont été modifiés

Document Fields (Signatory uniquement)

Le champ document_fields contient les valeurs des champs de formulaire remplis par le signataire. Seuls les champs avec des valeurs non vides sont inclus.

Exemple :

{
  "document_fields": {
    "company_name": "ACME Corp",
    "position": "CEO",
    "birth_date": "1980-05-12",
    "phone_number": "+33612345678"
  }
}

Authentification

Callback Secret

Les webhooks peuvent être sécurisés avec un callback_secret qui est ajouté en paramètre d'URL :

https://votre-serveur.com/webhook?callback_secret=votre_secret_ici

Le secret est configuré lors de la création de la transaction et est automatiquement ajouté à toutes les requêtes webhook.

Vérification de sécurité

Il est recommandé de :

1. Vérifier le callback_secret dans vos webhooks
2. Utiliser HTTPS pour toutes les URLs de webhook
3. Valider les UUIDs reçus contre votre base de données
4. Implémenter une idempotence pour gérer les tentatives multiples

Mécanisme de retry

Les webhooks sont envoyés de manière asynchrone avec un système de retry :

Pour les événements Signatory :

• Nombre de tentatives : 3
• Délais entre tentatives : 15 secondes, 60 secondes, 120 secondes
• Timeout : 10 secondes par requête

Pour les événements Transaction :

• Nombre de tentatives : 3
• Délais entre tentatives : 300 secondes (5 min), 600 secondes (10 min), 1200 secondes (20 min)
• Timeout : 10 secondes par requête

⚠️ Important : Votre endpoint doit répondre avec un code HTTP 2xx pour être considéré comme réussi.

Exemples d'implémentation

PHP (Laravel)

Route::post('/webhook/secusign', function (Request $request) {
    // Vérifier le callback secret
    $expectedSecret = config('secusign.callback_secret');
    if ($request->input('callback_secret') !== $expectedSecret) {
        abort(403, 'Invalid callback secret');
    }

    $event = $request->input('event');
    $signatoryUid = $request->input('signatory_uid');
    $transactionUid = $request->input('transaction_uid');

    switch ($event) {
        case 'signatory.status.signed':
            // Traiter la signature
            $date = $request->input('date');
            $documentFields = $request->input('document_fields', []);
            // Votre logique métier ici
            break;

        case 'transaction.status.completed':
            // Traiter la fin de transaction
            // Votre logique métier ici
            break;

        // Autres cas...
    }

    return response()->json(['success' => true]);
});

Node.js (Express)

app.post('/webhook/secusign', (req, res) => {
    // Vérifier le callback secret
    const expectedSecret = process.env.SECUSIGN_CALLBACK_SECRET;
    if (req.body.callback_secret !== expectedSecret) {
        return res.status(403).send('Invalid callback secret');
    }

    const { event, signatory_uid, transaction_uid, changed_fields } = req.body;

    switch (event) {
        case 'signatory.status.signed':
            // Traiter la signature
            const { date, document_fields } = req.body;
            // Votre logique métier ici
            break;

        case 'transaction.status.completed':
            // Traiter la fin de transaction
            // Votre logique métier ici
            break;

        // Autres cas...
    }

    res.json({ success: true });
});

Diagramme de flux

Workflow de signature standard

sequenceDiagram
    participant Admin as Administrateur
    participant Signatory as Signataire
    participant SS as SecuSign
    participant Webhook as Votre Webhook
    participant Queue as File d'attente

    Admin->>SS: Créer transaction
    SS->>Queue: transaction.created
    Queue->>Webhook: POST transaction.created
    Webhook-->>Queue: 200 OK

    Admin->>Signatory: Envoyer lien de signature
    
    Signatory->>SS: Accéder au document (1er accès)
    SS->>Queue: transaction.status.sent
    Queue->>Webhook: POST transaction.status.sent
    Webhook-->>Queue: 200 OK

    Signatory->>SS: Signer le document
    SS->>Queue: signatory.status.signed
    Queue->>Webhook: POST signatory.status.signed
    Webhook-->>Queue: 200 OK

    Note over SS: Tous les signataires ont signé
    SS->>Queue: transaction.status.completed
    Queue->>Webhook: POST transaction.status.completed
    Webhook-->>Queue: 200 OK

Workflow d'expiration

sequenceDiagram
    participant Admin as Administrateur
    participant SS as SecuSign
    participant Webhook as Votre Webhook
    participant Queue as File d'attente
    participant Cron as Tâche planifiée

    Admin->>SS: Créer transaction (expiration: 30j)
    SS->>Queue: transaction.created
    Queue->>Webhook: POST transaction.created

    Note over SS,Cron: 30 jours s'écoulent...
    Note over SS: Transaction non complétée
    
    Cron->>SS: Vérifier transactions expirées
    SS->>SS: Marquer comme expired
    SS->>Queue: transaction.status.expired
    Queue->>Webhook: POST transaction.status.expired
    Webhook-->>Queue: 200 OK

Workflow de complétion forcée

sequenceDiagram
    participant Admin as Administrateur
    participant API as API SecuSign
    participant SS as SecuSign
    participant Webhook as Votre Webhook
    participant Queue as File d'attente

    Admin->>API: POST /transaction/{uid}/complete
    API->>SS: Forcer statut completed
    SS->>Queue: transaction.status.completed
    Queue->>Webhook: POST transaction.status.completed
    Webhook-->>Queue: 200 OK

Questions fréquentes

Q: Puis-je recevoir les webhooks sur plusieurs URLs ?

R: Non, une seule URL webhook peut être configurée par transaction. Vous devrez redistribuer les événements depuis votre endpoint.

Q: Que se passe-t-il si mon endpoint est temporairement indisponible ?

R: Le système tentera de renvoyer le webhook selon le mécanisme de retry configuré (3 tentatives avec délais croissants).

Q: Quand est-ce que le statut "sent" est déclenché ?

R: Le statut "sent" est déclenché dès qu'un signataire accède pour la première fois à la visualisation du document, pas lors de l'envoi initial des invitations.

Q: Puis-je forcer une transaction au statut "completed" ?

R: Oui, il est possible de forcer le passage au statut "completed" via un appel API, même si tous les signataires n'ont pas signé. Cela déclenche le webhook transaction.status.completed.

Q: Comment tester mes webhooks en développement ?

R: Utilisez des outils comme ngrok ou webhook.site pour exposer votre environnement local.