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-subscriptionsont obsolètes et seront supprimés le 31 octobre 2026 :
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscriptionGET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscriptionDELETE /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscriptionMigrez vers les nouveaux endpoints
webhooksdé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 :
| Niveau | Portée | Événements pris en charge |
|---|---|---|
| Enveloppe | Une seule enveloppe | Tous les événements (voir Événements pris en charge) |
| Organisation | Toutes les enveloppes de l'organisation | EnvelopeCompleted 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.
GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks
Retourne tous les webhooks configurés pour l'enveloppe spécifiée.
| Nom | Type | Requis | Description |
|---|---|---|---|
organizationId | string (uuid) | Oui | Identifiant unique de l'organisation |
envelopeId | string (uuid) | Oui | Identifiant unique de l'enveloppe |
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks
Crée un webhook pour l'enveloppe spécifiée.
| Nom | Type | Requis | Description |
|---|---|---|---|
organizationId | string (uuid) | Oui | Identifiant unique de l'organisation |
envelopeId | string (uuid) | Oui | Identifiant unique de l'enveloppe |
Content-Type : application/json
| Champ | Type | Requis | Description |
|---|---|---|---|
url | string | Oui | L'URL HTTPS destinée à recevoir les événements webhook |
event | WebhookEventType (string) | Oui | L'événement qui déclenche le webhook. Voir Événements pris en charge |
authentication | WebhookAuthenticationRequest | Non | Paramètres d'authentification pour l'endpoint webhook |
| Événement | Description |
|---|---|
EnvelopeSent | L'enveloppe a été envoyée |
EnvelopeCompleted | L'enveloppe a été complétée* |
EnvelopeCanceled | L'enveloppe a été annulée |
EnvelopeRestarted | L'enveloppe a été redémarrée |
EnvelopeDeleted | L'enveloppe a été supprimée |
RecipientCompleted | Un destinataire a finalisé son action |
RecipientRejected | Un destinataire a rejeté l'enveloppe |
RecipientDelegated | Un 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.
| Champ | Type | Nullable | Description |
|---|---|---|---|
headers | object (map<string, string>) | Oui | En-têtes HTTP optionnels à inclure dans les appels webhook, par exemple un en-tête Authorization |
clientCertificate | string | Oui | Certificat client encodé PEM optionnel pour mTLS |
clientKey | string | Oui | Clé privée encodée PEM optionnelle pour mTLS |
{
"url": "https://example.com/hooks/envelope",
"event": "EnvelopeCompleted",
"authentication": {
"headers": {
"Authorization": "Bearer token_123"
}
}
}{
"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"
}
}{
"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://"
}
}
]
}
}GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}
Retourne le webhook spécifié.
| Nom | Type | Requis | Description |
|---|---|---|---|
organizationId | string (uuid) | Oui | Identifiant unique de l'organisation |
envelopeId | string (uuid) | Oui | Identifiant unique de l'enveloppe |
webhookId | string (uuid) | Oui | Identifiant unique du webhook |
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.
| Nom | Type | Requis | Description |
|---|---|---|---|
organizationId | string (uuid) | Oui | Identifiant unique de l'organisation |
envelopeId | string (uuid) | Oui | Identifiant unique de l'enveloppe |
webhookId | string (uuid) | Oui | Identifiant unique du webhook |
{
"url": "https://example.com/hooks/envelope-new",
"event": "EnvelopeCompleted",
"authentication": {
"headers": {
"Authorization": "Bearer token_123"
}
}
}DELETE /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}
Supprime le webhook spécifié.
| Nom | Type | Requis | Description |
|---|---|---|---|
organizationId | string (uuid) | Oui | Identifiant unique de l'organisation |
envelopeId | string (uuid) | Oui | Identifiant unique de l'enveloppe |
webhookId | string (uuid) | Oui | Identifiant unique du webhook |
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.
GET /api/v1/organizations/{organizationId}/webhooks
Retourne tous les webhooks configurés pour l'organisation spécifiée.
| Nom | Type | Requis | Description |
|---|---|---|---|
organizationId | string (uuid) | Oui | Identifiant unique de l'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.
| Nom | Type | Requis | Description |
|---|---|---|---|
organizationId | string (uuid) | Oui | Identifiant unique de l'organisation |
Content-Type : application/json
Corps de la requête (CreateOrganizationWebhookRequest) pour la création d'un webhook d'organisation.
| Champ | Type | Requis | Description |
|---|---|---|---|
url | string | Oui | L'URL HTTPS destinée à recevoir les événements webhook |
event | WebhookEventType (string) | Oui | L'événement qui déclenche le webhook. Pour les webhooks d'organisation, seul EnvelopeCompleted est pris en charge |
authentication | WebhookAuthenticationRequest | Non | Paramètres d'authentification pour l'endpoint webhook |
{
"url": "https://example.com/hooks/organization",
"event": "EnvelopeCompleted",
"authentication": {
"headers": {
"Authorization": "Bearer token_123"
}
}
}GET /api/v1/organizations/{organizationId}/webhooks/{webhookId}
Retourne le webhook d'organisation spécifié.
| Nom | Type | Requis | Description |
|---|---|---|---|
organizationId | string (uuid) | Oui | Identifiant unique de l'organisation |
webhookId | string (uuid) | Oui | Identifiant unique du webhook |
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.
| Nom | Type | Requis | Description |
|---|---|---|---|
organizationId | string (uuid) | Oui | Identifiant unique de l'organisation |
webhookId | string (uuid) | Oui | Identifiant unique du webhook |
{
"url": "https://example.com/hooks/organization-new",
"event": "EnvelopeCompleted",
"authentication": {
"headers": {
"Authorization": "Bearer token_123"
}
}
}DELETE /api/v1/organizations/{organizationId}/webhooks/{webhookId}
Supprime le webhook d'organisation spécifié.
| Nom | Type | Requis | Description |
|---|---|---|---|
organizationId | string (uuid) | Oui | Identifiant unique de l'organisation |
webhookId | string (uuid) | Oui | Identifiant unique du webhook |
Les anciens endpoints webhook-subscription sont obsolètes et seront supprimés le 31 octobre 2026. Pour migrer :
| Endpoint obsolète | Remplacement |
|---|---|
POST .../envelopes/{envelopeId}/webhook-subscription | POST .../envelopes/{envelopeId}/webhooks (le champ event est désormais requis) |
GET .../envelopes/{envelopeId}/webhook-subscription | GET .../envelopes/{envelopeId}/webhooks ou GET .../envelopes/{envelopeId}/webhooks/{webhookId} |
DELETE .../envelopes/{envelopeId}/webhook-subscription | DELETE .../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.