Met een webhook laat Penneo uw eigen systeem weten wanneer er iets gebeurt, bijvoorbeeld wanneer alle ondertekenaars een dossier hebben ondertekend. Penneo stuurt direct een kort bericht naar een webadres (URL) dat u kiest. Uw systeem hoeft Penneo dus niet steeds om updates te vragen.
Webhooks zijn bedoeld voor beheerders en ontwikkelaars die Penneo Sign koppelen aan een ander systeem, zoals een CRM, een ERP of hun eigen software.
Heb ik dit nodig? Als u alleen documenten ter ondertekening verstuurt in Penneo, gebruikt u geen webhooks en hoeft u niets te doen. Webhooks zijn alleen relevant als u, of een softwareleverancier die u gebruikt, een ander systeem aan Penneo hebt gekoppeld.
E-mail "Webhook delivery failed" of "Subscription disabled" ontvangen?
Penneo stuurt deze e-mail naar beheerders wanneer webhookberichten lange tijd niet bij uw systeem konden worden afgeleverd, en de webhook daarom is uitgeschakeld.
- Zoek uit wie hem heeft ingesteld. Meestal is het een koppeling van een andere softwareleverancier, of uw eigen IT-team. Stuur hen de e-mail door.
- Corrigeer het adres. Het systeem dat de berichten ontvangt, moet online zijn en bereikbaar via internet.
- Schakel de webhook weer in. Een beheerder kan dit doen via Configureren → Webhooks, of uw ontwikkelaar via de API.
Zolang hij niet weer is ingeschakeld, krijgt uw andere systeem geen bericht over nieuwe handtekeningen. Penneo Sign zelf blijft gewoon werken.
Een webhook instellen in Penneo (beheerders)
- Ga naar Configureren → Webhooks.
- Klik op Abonnement aanmaken.
- Vul bij URL het HTTPS-adres in waar uw systeem de events ontvangt.
- Vink onder Eventtypes de events aan die u wilt (zie de lijst hieronder). U kunt zoeken, of een hele groep aanvinken zoals CASEFILE of SIGNER.
- Klik op Abonnement aanmaken om op te slaan.
Klik op Testevenement verzenden op de pagina Webhooks om uw instelling te testen zodra u een abonnement hebt. Op dezelfde pagina kunt u abonnementen bekijken, bewerken en uitschakelen, en de afleverlogs van de afgelopen 30 dagen zien: welke berichten zijn afgeleverd, welke zijn mislukt en waarom.
Voordat u begint:
- Het adres moet bereikbaar zijn via internet. Adressen op uw eigen computer of intern netwerk (zoals localhost) werken niet.
- Test eerst met een gratis tool zoals Webhook.site, en abonneer u op het testevent
webhook.subscription.test.
Ziet u Webhooks niet onder Configureren? Alleen beheerders kunnen webhooks beheren. Andere gebruikers krijgen een melding dat ze geen toegang hebben tot de pagina. Vraag een beheerder in uw bedrijf om het in te stellen, of om u beheerdersrechten te geven.
Een webhook instellen via de API (ontwikkelaars)
Maak een abonnement aan met een POST-verzoek:
POST https://app.penneo.com/webhook/api/v1/subscriptions
{
"eventTypes": ["sign.casefile.completed", "sign.signer.signed"],
"endpoint": "https://example.com/webhook"
}
U kunt elke inlogmethode gebruiken die Penneo voor de API ondersteunt. Het antwoord bevat een secret waarmee u controleert of berichten echt van Penneo komen. Bewaar deze veilig.
U kunt abonnementen ook opvragen, bijwerken, verwijderen en testen via de API. Volledige referentie, voorbeelden en een Postman-collectie: Webhooks op developer.penneo.com en Postman collection for Penneo Webhooks. Zie Generating OAuth 2.0 Client Credentials om in te loggen op de API.
U kunt maximaal 5 actieve abonnementen per account hebben. Meer nodig? Neem contact op met support.
Events waarop u zich kunt abonneren
Eén abonnement kan meerdere events bevatten. Berichten gelden voor alle dossiers in uw account, ook die van uw collega's.
Dossier-events
| Event | Wanneer het wordt verstuurd |
|---|---|
sign.casefile.completed |
Iedereen heeft ondertekend en de ondertekende documenten zijn klaar om te downloaden. |
sign.casefile.expired |
Het dossier is verlopen voordat iedereen had ondertekend. |
sign.casefile.rejected |
Een of meer ondertekenaars hebben het ondertekeningsverzoek geweigerd. |
sign.casefile.failed |
Er ging iets mis aan de kant van Penneo. Neem contact op met support. |
Ondertekenaar-events
| Event | Wanneer het wordt verstuurd |
|---|---|
sign.signer.requestActivated |
De ondertekenaar kan nu ondertekenen: het dossier is geactiveerd, of het is zijn of haar beurt. |
sign.signer.requestSent |
De eerste e-mail met het ondertekeningsverzoek is verstuurd. |
sign.signer.reminderSent |
Er is een herinneringsmail verstuurd. |
sign.signer.requestOpened |
De ondertekenaar heeft de e-mail met het ondertekeningsverzoek geopend. |
sign.signer.opened |
De ondertekenaar heeft de ondertekeningspagina geopend. |
sign.signer.signed |
De ondertekenaar heeft ondertekend. |
sign.signer.rejected |
De ondertekenaar heeft het ondertekeningsverzoek geweigerd. |
sign.signer.finalized |
Het dossier waartoe deze ondertekenaar behoort, is afgerond. |
sign.signer.deleted |
De ondertekenaar is uit het dossier verwijderd. |
sign.signer.undeliverable |
Penneo kan geen e-mails naar de ondertekenaar sturen. Controleer het e-mailadres. |
sign.signer.transientBounce |
Een e-mail naar de ondertekenaar is tijdelijk teruggestuurd. |
sign.signer.signedWithImageUploadAndNAP |
De ondertekenaar heeft ondertekend met een afbeeldingsupload en NAP (alleen als uw ondertekeningsstroom dit gebruikt). |
Testevent
| Event | Wanneer het wordt verstuurd |
|---|---|
webhook.subscription.test |
Wanneer u een test start, om te controleren of uw adres berichten ontvangt. |
Sommige ondertekenaar-events, zoals requestSent, opened en signed, kunnen meer dan eens komen als een ondertekenaar in meerdere rondes ondertekent.
Inhoud van een bericht
Berichten zijn bewust kort. Ze vertellen wat er gebeurde en het ID van het dossier of de ondertekenaar, bijvoorbeeld:
{
"topic": "casefile",
"eventType": "completed",
"eventTime": { "date": "2026-01-01 12:59:59.000000", "timezone_type": 3, "timezone": "UTC" },
"payload": { "id": <dossier-ID>, "status": <statuscode> }
}
Gebruik het ID om het dossier via de API op te halen voor meer details, zoals de ondertekenaars of de ondertekende documenten. Om dossiers van collega's te lezen, heeft de API-gebruiker daar toegang toe nodig.
Maak uw adres betrouwbaar
- Reageer snel. Uw systeem moet de verbinding binnen 500 ms accepteren en binnen 1,5 seconde antwoorden. Sla het bericht op, antwoord direct met een 2xx-status en verwerk het daarna.
- Alleen 2xx telt als afgeleverd. Elk ander antwoord, of geen antwoord, laat Penneo het opnieuw proberen.
-
Houd rekening met dubbele berichten. Elk bericht heeft een unieke
X-Event-Id-header. Onthoud de ID's een tijdje en sla berichten over die u al hebt verwerkt. -
Controleer de handtekening. Elk bericht heeft een
X-Event-Signature-header, ondertekend met de secret van uw abonnement (HMAC-SHA256). We raden sterk aan deze te controleren. Zie hoe u de handtekening controleert.
Als aflevering mislukt, probeert Penneo het binnen ongeveer de eerste minuut 5 keer opnieuw, en daarna 30 uur lang één keer per uur. Als geen van deze pogingen lukt, schakelt Penneo het abonnement uit en mailt de maker en alle beheerders. Corrigeer het adres en schakel het abonnement daarna weer in.
Gebruikt u de oude webhookdienst?
De oude webhookdienst van Penneo stopt op 30 november 2026. Gebruikt uw koppeling die nog, stap dan vóór die datum over op de webhooks in dit artikel. Zie de migratiehandleiding. Twijfelt u? Vraag het uw softwareleverancier of ontwikkelaar.
Komt u er nog niet uit?
Gebruik de chat. Ons supportteam helpt u met webhooks, de API en uw koppeling.
U kunt de chat ook altijd openen met de chatknop rechtsonder.