API native WakaSign

Workflow complet : créer un token, créer une enveloppe, l'envoyer, puis recevoir les événements du Workflow via webhook.

Pré-requis communs

Tous les tutoriels partagent le même mécanisme d'authentification.

Chaque appel HTTP doit porter un header Authorization: Bearer <token> où <token> est un token dk_… généré dans l'app WakaSign (menu Clés API & Webhooks). Le token est lié à un workspace (team) — toutes les opérations s'effectuent dans son périmètre.

Base URL : https://app.wakasign.com/api

Envoyer des documents avec l'API native

Récupérer le teamId du workspace cible

L'endpoint d'envoi accepte un teamId numérique. Récupère-le via GET /api/proxy/teams côté UI, ou via la base directement.

Créer une enveloppe (DRAFT)

bash

curl -X POST 'https://app.wakasign.com/api/envelopes/team/<TEAM_ID>' \
  -H 'Authorization: Bearer dk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Contrat de prestation",
    "message": "Bonjour, merci de signer ce document.",
    "visibility": "EVERYONE",
    "signingOrder": "PARALLEL",
    "distributionMethod": "EMAIL",
    "recipients": [
      { "email": "client@example.com", "name": "Jean Dupont", "role": "SIGNER" }
    ]
  }'

La réponse contient un id d'enveloppe (état DRAFT) — c'est cet identifiant qu'on utilise pour les étapes suivantes.

Uploader le fichier PDF

bash

curl -X POST 'https://app.wakasign.com/api/envelopes/team/<TEAM_ID>/<ENVELOPE_ID>/upload' \
  -H 'Authorization: Bearer dk_xxx' \
  -F 'file=@contrat.pdf'

Envoyer aux signataires

bash

curl -X POST 'https://app.wakasign.com/api/envelopes/team/<TEAM_ID>/<ENVELOPE_ID>/send' \
  -H 'Authorization: Bearer dk_xxx'

Chaque signataire reçoit un email contenant le lien de signature. L'enveloppe passe à l'état SENT.

Suivre l'avancement via webhooks

Plutôt que de poller GET /api/envelopes/team/<TEAM_ID>/<ID>, branche un webhook qui sera appelé à chaque transition d'état du Workflow.

Webhooks — événements du Workflow

WakaSign POST chaque événement sur l'URL configurée pour le workspace.

Événements disponibles

DOCUMENT_CREATEDUne enveloppe vient d'être créée à l'état DRAFT.

DOCUMENT_SENTUne enveloppe a été envoyée à ses signataires.

DOCUMENT_OPENEDLe premier signataire a ouvert le lien d'invitation.

DOCUMENT_SIGNEDUn signataire individuel vient de signer (déclenché à chaque signature).

DOCUMENT_COMPLETEDTous les signataires ont signé — le document est finalisé.

DOCUMENT_REJECTEDUn signataire a refusé de signer.

DOCUMENT_CANCELLEDL'enveloppe a été annulée par l'émetteur.

Forme du payload reçu

json

{
  "event_id": "evt_abc123",
  "event": "DOCUMENT_COMPLETED",
  "event_time": "2026-05-15T10:42:18.523Z",
  "team_id": 42,
  "data": {
    "envelope": {
      "id": "env_abc123",
      "status": "COMPLETED",
      "title": "Contrat de prestation",
      "externalId": null,
      "createdAt": "2026-05-15T09:10:00.000Z",
      "completedAt": "2026-05-15T10:42:18.523Z"
    },
    "recipient": {
      "id": 7,
      "email": "client@example.com",
      "name": "Jean Dupont",
      "role": "SIGNER"
    }
  }
}

Vérifier la signature HMAC

WakaSign signe chaque appel avec HMAC-SHA256 sur ${timestamp}.${body} (le timestamp Unix en secondes, envoyé dans X-WakaSign-Timestamp), en utilisant le secret du webhook. La signature est envoyée dans le header X-WakaSign-Signature au format sha256=<hex>.

javascript

const crypto = require('crypto');

app.post('/webhooks/wakasign', (req, res) => {
  const timestamp = req.header('X-WakaSign-Timestamp');
  const signature = req.header('X-WakaSign-Signature');
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WAKASIGN_WEBHOOK_SECRET)
    .update(`${timestamp}.${req.rawBody}`)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('invalid signature');
  }
  const { event, data } = req.body;
  // … traite l'événement ici
  res.status(200).send('ok');
});