Un webhook permet à Penneo d'informer votre propre système lorsqu'un événement se produit, par exemple quand tous les signataires ont signé un dossier. Penneo envoie immédiatement un court message à une adresse web (URL) de votre choix. Votre système n'a pas besoin d'interroger Penneo en permanence.
Les webhooks s'adressent aux administrateurs et aux développeurs qui connectent Penneo Sign à un autre système, comme un CRM, un ERP ou leur propre logiciel.
En ai-je besoin ? Si vous envoyez seulement des documents à signer dans Penneo, vous n'utilisez pas de webhooks et n'avez rien à faire. Les webhooks ne vous concernent que si vous, ou un éditeur de logiciel que vous utilisez, avez connecté un autre système à Penneo.
Vous avez reçu l'e-mail « Webhook delivery failed » ou « Subscription disabled » ?
Penneo envoie cet e-mail aux administrateurs lorsqu'il n'a pas pu livrer les messages webhook à votre système pendant longtemps, et a donc désactivé le webhook.
- Identifiez qui l’a configuré. Il s'agit généralement d'une intégration d'un autre éditeur de logiciel, ou de votre équipe informatique. Transférez-leur l'e-mail.
- Corrigez l’adresse. Le système qui reçoit les messages doit être en ligne et accessible depuis Internet.
- Réactivez le webhook. Un administrateur peut le faire dans Configurer → Webhooks, ou votre développeur via l'API.
Tant qu'il n'est pas réactivé, votre autre système ne sera pas informé des nouvelles signatures. Penneo Sign continue de fonctionner normalement.
Configurer un webhook dans Penneo (administrateurs)
- Allez dans Configurer → Webhooks.
- Cliquez sur Souscrire un abonnement.
- Dans URL, saisissez l'adresse HTTPS où votre système reçoit les événements.
- Sous Types d’événements, cochez les événements souhaités (voir la liste ci-dessous). Vous pouvez rechercher, ou cocher un groupe entier comme CASEFILE ou SIGNER.
- Cliquez sur Souscrire un abonnement pour enregistrer.
Pour tester votre configuration, cliquez sur Envoyer un événement test sur la page Webhooks une fois que vous avez un abonnement. Sur la même page, vous pouvez consulter, modifier et désactiver les abonnements, et voir les journaux de livraison des 30 derniers jours : quels messages ont été livrés, lesquels ont échoué et pourquoi.
Avant de commencer :
- L'adresse doit être accessible depuis Internet. Les adresses de votre ordinateur ou de votre réseau interne (comme localhost) ne fonctionnent pas.
- Testez d'abord avec un outil gratuit comme Webhook.site, et abonnez-vous à l'événement de test
webhook.subscription.test.
Vous ne voyez pas Webhooks dans Configurer ? Seuls les administrateurs peuvent gérer les webhooks. Les autres utilisateurs voient un message indiquant qu'ils n'ont pas accès à la page. Demandez à un administrateur de votre entreprise de le configurer, ou de vous donner les droits d'administrateur.
Configurer un webhook via l'API (développeurs)
Créez un abonnement avec une requête POST :
POST https://app.penneo.com/webhook/api/v1/subscriptions
{
"eventTypes": ["sign.casefile.completed", "sign.signer.signed"],
"endpoint": "https://example.com/webhook"
}
Vous pouvez utiliser toutes les méthodes de connexion à l'API prises en charge par Penneo. La réponse contient un secret qui vous permet de vérifier que les messages proviennent bien de Penneo. Conservez-le en lieu sûr.
Vous pouvez aussi lister, modifier, supprimer et tester des abonnements via l'API. Référence complète, exemples et collection Postman : Webhooks sur developer.penneo.com et Postman collection for Penneo Webhooks. Pour vous connecter à l'API, voir Generating OAuth 2.0 Client Credentials.
Vous pouvez avoir jusqu'à 5 abonnements actifs par compte. Besoin de plus ? Contactez le support.
Événements auxquels vous pouvez vous abonner
Un abonnement peut inclure plusieurs événements. Les messages couvrent tous les dossiers de votre compte, y compris ceux créés par vos collègues.
Événements de dossier
| Événement | Quand il est envoyé |
|---|---|
sign.casefile.completed |
Tout le monde a signé, et les documents signés sont prêts à être téléchargés. |
sign.casefile.expired |
Le dossier a expiré avant que tout le monde ait signé. |
sign.casefile.rejected |
Un ou plusieurs signataires ont refusé la demande de signature. |
sign.casefile.failed |
Une erreur s'est produite du côté de Penneo. Contactez le support. |
Événements de signataire
| Événement | Quand il est envoyé |
|---|---|
sign.signer.requestActivated |
Le signataire peut signer maintenant : le dossier a été activé, ou c'est son tour. |
sign.signer.requestSent |
Le premier e-mail de demande de signature a été envoyé. |
sign.signer.reminderSent |
Un e-mail de rappel a été envoyé. |
sign.signer.requestOpened |
Le signataire a ouvert l'e-mail de demande de signature. |
sign.signer.opened |
Le signataire a ouvert la page de signature. |
sign.signer.signed |
Le signataire a signé. |
sign.signer.rejected |
Le signataire a refusé la demande de signature. |
sign.signer.finalized |
Le dossier auquel appartient ce signataire est finalisé. |
sign.signer.deleted |
Le signataire a été retiré du dossier. |
sign.signer.undeliverable |
Penneo ne peut pas envoyer d'e-mails au signataire. Vérifiez son adresse e-mail. |
sign.signer.transientBounce |
Un e-mail au signataire a été temporairement rejeté. |
sign.signer.signedWithImageUploadAndNAP |
Le signataire a signé avec un téléchargement d'image et NAP (seulement si votre flux de signature l'utilise). |
Événement de test
| Événement | Quand il est envoyé |
|---|---|
webhook.subscription.test |
Lorsque vous déclenchez un test, pour vérifier que votre adresse reçoit les messages. |
Certains événements de signataire, comme requestSent, opened et signed, peuvent arriver plusieurs fois si un signataire signe en plusieurs phases.
Contenu d'un message
Les messages sont volontairement courts. Ils indiquent ce qui s'est passé et l'ID du dossier ou du signataire, par exemple :
{
"topic": "casefile",
"eventType": "completed",
"eventTime": { "date": "2026-01-01 12:59:59.000000", "timezone_type": 3, "timezone": "UTC" },
"payload": { "id": <ID du dossier>, "status": <code de statut> }
}
Pour obtenir plus de détails, comme les signataires ou les documents signés, utilisez l'ID pour récupérer le dossier via l'API. Pour lire les dossiers créés par vos collègues, l'utilisateur API doit y avoir accès.
Rendre votre adresse fiable
- Répondez rapidement. Votre système doit accepter la connexion en moins de 500 ms et répondre en moins de 1,5 seconde. Enregistrez le message et répondez immédiatement avec un statut 2xx, puis traitez-le ensuite.
- Seul un 2xx compte comme livré. Toute autre réponse, ou l'absence de réponse, déclenche une nouvelle tentative.
-
Attendez-vous à des doublons. Chaque message possède un en-tête
X-Event-Idunique. Conservez les ID pendant un certain temps et ignorez ceux que vous avez déjà traités. -
Vérifiez la signature. Chaque message possède un en-tête
X-Event-Signature, signé avec le secret de votre abonnement (HMAC-SHA256). Nous recommandons vivement de le vérifier. Voir comment vérifier la signature.
En cas d’échec de livraison, Penneo réessaie 5 fois pendant environ la première minute, puis une fois par heure pendant 30 heures. Si aucune tentative ne réussit, Penneo désactive l'abonnement et envoie un e-mail à la personne qui l'a créé et à tous les administrateurs. Corrigez l'adresse, puis réactivez l'abonnement.
Vous utilisez l'ancien service de webhooks ?
L'ancien service de webhooks de Penneo s'arrête le 30 novembre 2026. Si votre intégration l'utilise encore, passez aux webhooks décrits dans cet article avant cette date. Voir le guide de migration. Vous n'êtes pas sûr ? Demandez à votre éditeur de logiciel ou à votre développeur.
Toujours bloqué ?
Utilisez le chat. Notre équipe support peut vous aider avec les webhooks, l'API et votre intégration.
Vous pouvez aussi ouvrir le chat à tout moment avec le bouton de chat en bas à droite.