Événements webhook¶

Types d'événements¶

Événement	Description
`request.completed`	Tous les signataires ont signé la demande
`hello`	Événement de test envoyé lorsque vous vérifiez votre endpoint lors de la configuration/débogage (toujours livré à la demande manuelle)

D'autres types d'événements seront ajoutés à l'avenir. Vous pouvez configurer le webhook pour recevoir tous les types d'événements (actuels et futurs).

Pour les instructions de configuration et la vérification des signatures, consultez Configurer les webhooks.

En-têtes HTTP¶

VoidSign livre les webhooks sous forme de requêtes POST avec les en-têtes suivants :

En-tête	Description
`Content-Type`	`application/json`
`User-Agent`	`VoidSign-Webhook/1.0`
`webhook-id`	Identifiant unique de livraison (`msg_<uuid>`)
`webhook-timestamp`	Horodatage Unix (secondes) de l'envoi de l'événement
`webhook-signature`	Signature HMAC-SHA256 (`v1,<base64>`)

Exemple de requête HTTP brute :

POST /webhooks/voidsign HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: VoidSign-Webhook/1.0
webhook-id: msg_a1b2c3d4-e5f6-7890-abcd-ef1234567890
webhook-timestamp: 1742140948
webhook-signature: v1,U2lnbmF0dXJlIG9mIGEgdm9pZHNpZ24gbWVzc2FnZQ==

{"data":{"request_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"timestamp":"2026-03-16T17:42:28Z","type":"request.completed"}

Schémas de payload¶

hello : événement de test :

{
  "type": "hello",
  "timestamp": "2026-03-16T17:42:28Z"
}

request.completed : tous les signataires ont signé :

{
  "type": "request.completed",
  "timestamp": "2026-03-16T17:42:28Z",
  "data": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Propriétés du payload¶

La valeur du webhook-id est unique pour chaque événement VoidSign, ceci vous permet d'assurer l'idempotence au sein de votre propre système pour gérer les payloads rejoués.
La valeur de l'en-tête webhook-timestamp est l'horodatage utilisé pour la signature mais pas l'horodatage de l'événement. Consultez l'avertissement ci-dessous.
La valeur de l'en-tête webhook-signature est la signature attendue de la requête. Consultez Vérifier les signatures.
Le type d'événement est toujours fourni dans le corps de la requête au chemin JSON .type.
L'horodatage de l'événement est toujours fourni dans le corps de la requête au chemin JSON .timestamp.
Les données de l'événement sont toujours fournies dans le corps de la requête au chemin JSON .data. Les schémas spécifiques dépendent du type d'événement.

Horodatage des données vs horodatage du webhook

L'horodatage des données, c'est-à-dire l'horodatage présent dans le corps de la requête, représente le moment où l'événement s'est produit (par exemple, quand le dernier signataire a signé).
L'horodatage du webhook, c'est-à-dire la valeur de l'en-tête webhook-timestamp, correspond au moment où la livraison a été tentée par les serveurs VoidSign.

Comportement de réessai¶

Si votre endpoint ne retourne pas une réponse 2xx, VoidSign retente la livraison avec un backoff exponentiel sur de courtes durées, puis un backoff linéaire sur de plus longues durées. Les livraisons qui ne peuvent pas être complétées sont finalement abandonnées.

Votre endpoint doit être idempotent : utilisez l'en-tête webhook-id pour détecter les livraisons en double et éviter de traiter le même événement deux fois.

Calendrier de réessai

Le calendrier exact de réessai pourra être mis à jour à l'avenir pour s'aligner sur la spécification de réessai Standard Webhooks.