Passer au contenu

Webhooks

Gérer les webhooks pour les événements d'enveloppe, au niveau de l'enveloppe et au niveau de l'organisation.


Avis d'obsolescence

Les endpoints webhook-subscription sont obsolètes et seront supprimés le 31 octobre 2026 :

  • POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscription
  • GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscription
  • DELETE /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscription

Migrez vers les nouveaux endpoints webhooks décrits ci-dessous avant cette date. Après leur suppression, les appels aux anciens endpoints échoueront. Voir Migration depuis webhook-subscription.


Les webhooks permettent à votre application de recevoir des notifications en temps réel sur les événements d'enveloppe. Au lieu d'interroger l'API pour obtenir des mises à jour de statut, NSE envoie un événement à votre endpoint HTTPS dès que l'événement auquel vous êtes abonné se produit.

Les webhooks peuvent être enregistrés à deux niveaux :

NiveauPortéeÉvénements pris en charge
EnveloppeUne seule enveloppeTous les événements (voir Événements pris en charge)
OrganisationToutes les enveloppes de l'organisationEnvelopeCompleted uniquement

Pour les deux niveaux, vous enregistrez une URL webhook et sélectionnez l'événement qui doit la déclencher (par exemple EnvelopeCompleted ou RecipientRejected). Chaque webhook possède son propre webhookId, que vous utilisez pour le consulter, le mettre à jour ou le supprimer.


Webhooks d'enveloppe

Lister les webhooks d'une enveloppe

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks

Retourne tous les webhooks configurés pour l'enveloppe spécifiée.

Paramètres de chemin

NomTypeRequisDescription
organizationIdstring (uuid)OuiIdentifiant unique de l'organisation
envelopeIdstring (uuid)OuiIdentifiant unique de l'enveloppe

Créer un webhook d'enveloppe

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks

Crée un webhook pour l'enveloppe spécifiée.

Paramètres de chemin

NomTypeRequisDescription
organizationIdstring (uuid)OuiIdentifiant unique de l'organisation
envelopeIdstring (uuid)OuiIdentifiant unique de l'enveloppe

Corps de la requête

Content-Type : application/json

ChampTypeRequisDescription
urlstringOuiL'URL HTTPS destinée à recevoir les événements webhook
eventWebhookEventType (string)OuiL'événement qui déclenche le webhook. Voir Événements pris en charge
authenticationWebhookAuthenticationRequestNonParamètres d'authentification pour l'endpoint webhook

Événements pris en charge

ÉvénementDescription
EnvelopeSentL'enveloppe a été envoyée
EnvelopeCompletedL'enveloppe a été complétée*
EnvelopeCanceledL'enveloppe a été annulée
EnvelopeRestartedL'enveloppe a été redémarrée
EnvelopeDeletedL'enveloppe a été supprimée
RecipientCompletedUn destinataire a finalisé son action
RecipientRejectedUn destinataire a rejeté l'enveloppe
RecipientDelegatedUn destinataire a délégué son action

*Lorsque la fonctionnalité EnrichedWebhook est activée, l'événement EnvelopeCompleted renvoie des données supplémentaires, par exemple les étapes, les destinataires, les artefacts et les métadonnées de la catégorie de documents.

WebhookAuthenticationRequest

ChampTypeNullableDescription
headersobject (map<string, string>)OuiEn-têtes HTTP optionnels à inclure dans les appels webhook, par exemple un en-tête Authorization
clientCertificatestringOuiCertificat client encodé PEM optionnel pour mTLS
clientKeystringOuiClé privée encodée PEM optionnelle pour mTLS

Exemple de requête

{
  "url": "https://example.com/hooks/envelope",
  "event": "EnvelopeCompleted",
  "authentication": {
    "headers": {
      "Authorization": "Bearer token_123"
    }
  }
}

Exemple de payload - enveloppe complétée (sans la fonctionnalité EnrichedWebhook)

{
  "type": "EnvelopeCompleted",
  "id": "cf02da82-1234-1234-1234-f07c9fafb1d0",
  "occurredAt": "2026-11-17T08:12:17.767+00:00",
  "organizationId": "afa1c381-1234-1234-1234-6e6796af7ff3",
  "envelope": {
    "id": "6af2128b-1234-1234-1234-881581c104c3",
    "status": "Completed"
  }
}

Exemple de payload - enveloppe complétée (avec la fonctionnalité EnrichedWebhook)

{
  "type": "EnvelopeCompleted",
  "id": "7d84ac88-1234-1234-1234-faae948cfe07",
  "occurredAt": "2026-11-17T08:16:44.947+00:00",
  "organizationId": "afa1c381-1234-1234-1234-6e6796af7ff3",
  "envelope": {
    "id": "f2c3c35d-1234-1234-1234-2a882bca7e19",
    "status": "Completed",
    "name": "Contract for Mario Rossi",
    "createdAt": "2026-11-17T08:15:49.637+00:00",
    "sentAt": "2026-11-17T08:16:18.976+00:00",
    "completedAt": "2026-11-17T08:16:42.701+00:00",
    "stages": [
      {
        "id": "5d501c26-1234-1234-1234-cdcdc5918d52",
        "name": "Stage3",
        "sortOrder": 1,
        "type": "Signer",
        "requiredRecipientCompletions": 1,
        "recipients": [
          {
            "id": "d92c57ca-1234-1234-1234-3931cc784a6e",
            "givenName": "Mario",
            "surname": "Rossi",
            "email": "m.gierlinger@namirial.com",
            "status": "Completed",
            "completedAt": "2026-11-17T08:16:42.374+00:00"
          }
        ]
      },
      {
        "id": "dc1ab1b6-1234-1234-1234-3ed51f23904e",
        "name": "",
        "sortOrder": 2,
        "type": "CarbonCopy",
        "requiredRecipientCompletions": 0,
        "recipients": [
          {
            "id": "d0965a53-1234-1234-1234-c88fc3db7f86",
            "givenName": "Mario",
            "surname": "Rossi",
            "email": "m.rossi@sample.com",
            "status": "Completed",
            "completedAt": "2026-11-17T08:16:42.701+00:00"
          }
        ]
      }
    ],
    "artifacts": [
      {
        "id": "cfe314d5-1234-1234-1234-24c974923fe5",
        "type": "CompletedFile",
        "name": "A.pdf",
        "fileId": "662806f3-1234-1234-1234-539c12ef097c",
        "downloadLink": {
          "url": "https://"
        }
      },
      {
        "id": "314676fd-1234-1234-1234-edfec12150ba",
        "type": "AuditTrail",
        "name": "Audit Trail.pdf",
        "downloadLink": {
          "url": "https://"
        }
      }
    ]
  }
}

Obtenir un webhook d'enveloppe

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}

Retourne le webhook spécifié.

Paramètres de chemin

NomTypeRequisDescription
organizationIdstring (uuid)OuiIdentifiant unique de l'organisation
envelopeIdstring (uuid)OuiIdentifiant unique de l'enveloppe
webhookIdstring (uuid)OuiIdentifiant unique du webhook

Mettre à jour un webhook d'enveloppe

PUT /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}

Met à jour le webhook spécifié. Le corps de la requête (UpdateEnvelopeWebhookRequest) a la même structure que pour Créer un webhook d'enveloppe : url et event sont requis, authentication est facultatif.

Paramètres de chemin

NomTypeRequisDescription
organizationIdstring (uuid)OuiIdentifiant unique de l'organisation
envelopeIdstring (uuid)OuiIdentifiant unique de l'enveloppe
webhookIdstring (uuid)OuiIdentifiant unique du webhook

Exemple de requête

{
  "url": "https://example.com/hooks/envelope-new",
  "event": "EnvelopeCompleted",
  "authentication": {
    "headers": {
      "Authorization": "Bearer token_123"
    }
  }
}

Supprimer un webhook d'enveloppe

DELETE /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}

Supprime le webhook spécifié.

Paramètres de chemin

NomTypeRequisDescription
organizationIdstring (uuid)OuiIdentifiant unique de l'organisation
envelopeIdstring (uuid)OuiIdentifiant unique de l'enveloppe
webhookIdstring (uuid)OuiIdentifiant unique du webhook

Webhooks d'organisation

Les webhooks d'organisation sont déclenchés pour l'événement correspondant sur toutes les enveloppes de l'organisation : vous n'avez donc pas besoin d'enregistrer un webhook pour chaque enveloppe.

Remarque

Les webhooks d'organisation ne prennent en charge que l'événement EnvelopeCompleted. Les webhooks d'enveloppe prennent en charge tous les événements listés dans Événements pris en charge.

Les structures de requête et de payload sont les mêmes que pour les webhooks d'enveloppe. Voir WebhookAuthenticationRequest et les exemples de payload ci-dessus. La fonctionnalité EnrichedWebhook s'applique également aux webhooks d'organisation.

Lister les webhooks d'une organisation

GET /api/v1/organizations/{organizationId}/webhooks

Retourne tous les webhooks configurés pour l'organisation spécifiée.

Paramètres de chemin

NomTypeRequisDescription
organizationIdstring (uuid)OuiIdentifiant unique de l'organisation

Créer un webhook d'organisation

POST /api/v1/organizations/{organizationId}/webhooks

Crée un nouveau webhook pour l'organisation spécifiée. Seul l'événement EnvelopeCompleted est pris en charge.

Paramètres de chemin

NomTypeRequisDescription
organizationIdstring (uuid)OuiIdentifiant unique de l'organisation

Corps de la requête

Content-Type : application/json

Corps de la requête (CreateOrganizationWebhookRequest) pour la création d'un webhook d'organisation.

ChampTypeRequisDescription
urlstringOuiL'URL HTTPS destinée à recevoir les événements webhook
eventWebhookEventType (string)OuiL'événement qui déclenche le webhook. Pour les webhooks d'organisation, seul EnvelopeCompleted est pris en charge
authenticationWebhookAuthenticationRequestNonParamètres d'authentification pour l'endpoint webhook

Exemple de requête

{
  "url": "https://example.com/hooks/organization",
  "event": "EnvelopeCompleted",
  "authentication": {
    "headers": {
      "Authorization": "Bearer token_123"
    }
  }
}

Obtenir un webhook d'organisation

GET /api/v1/organizations/{organizationId}/webhooks/{webhookId}

Retourne le webhook d'organisation spécifié.

Paramètres de chemin

NomTypeRequisDescription
organizationIdstring (uuid)OuiIdentifiant unique de l'organisation
webhookIdstring (uuid)OuiIdentifiant unique du webhook

Mettre à jour un webhook d'organisation

PUT /api/v1/organizations/{organizationId}/webhooks/{webhookId}

Met à jour le webhook d'organisation spécifié. Le corps de la requête a la même structure que pour Créer un webhook d'organisation : url et event sont requis, authentication est facultatif.

Paramètres de chemin

NomTypeRequisDescription
organizationIdstring (uuid)OuiIdentifiant unique de l'organisation
webhookIdstring (uuid)OuiIdentifiant unique du webhook

Exemple de requête

{
  "url": "https://example.com/hooks/organization-new",
  "event": "EnvelopeCompleted",
  "authentication": {
    "headers": {
      "Authorization": "Bearer token_123"
    }
  }
}

Supprimer un webhook d'organisation

DELETE /api/v1/organizations/{organizationId}/webhooks/{webhookId}

Supprime le webhook d'organisation spécifié.

Paramètres de chemin

NomTypeRequisDescription
organizationIdstring (uuid)OuiIdentifiant unique de l'organisation
webhookIdstring (uuid)OuiIdentifiant unique du webhook

Migration depuis webhook-subscription

Les anciens endpoints webhook-subscription sont obsolètes et seront supprimés le 31 octobre 2026. Pour migrer :

Endpoint obsolèteRemplacement
POST .../envelopes/{envelopeId}/webhook-subscriptionPOST .../envelopes/{envelopeId}/webhooks (le champ event est désormais requis)
GET .../envelopes/{envelopeId}/webhook-subscriptionGET .../envelopes/{envelopeId}/webhooks ou GET .../envelopes/{envelopeId}/webhooks/{webhookId}
DELETE .../envelopes/{envelopeId}/webhook-subscriptionDELETE .../envelopes/{envelopeId}/webhooks/{webhookId}

Changements à prendre en compte :

  • Les requêtes exigent désormais le champ event.
  • Les webhooks sont identifiés par un webhookId, nécessaire pour consulter, mettre à jour ou supprimer un webhook individuel.
  • Les webhooks peuvent désormais être mis à jour avec PUT, sans devoir les supprimer puis les recréer.