A webhook lets Penneo tell your own system when something happens, for example when all signers have signed a case file. Penneo sends a short message to a web address (URL) you choose, straight away. Your system doesn't have to keep asking Penneo for updates.
Webhooks are for Admins and developers who connect Penneo Sign to another system, such as a CRM, an ERP or their own software.
Do I need this? If you only send documents for signing in Penneo, you don't use webhooks and don't need to do anything. Webhooks only matter if you, or a software provider you use, have connected another system to Penneo.
Jump to
Got the "disabled" email?Set up in PenneoSet up with the APIEventsWhat a message containsReliability and retriesOld webhook serviceGot the email "Webhook delivery failed" or "Subscription disabled"?
Penneo sends this email to Admins when it couldn't deliver webhook messages to your system for a long time, and has therefore switched the webhook off.
- Find out who set it up. Usually it's an integration from another software provider, or your own IT team. Forward them the email.
- Fix the address. The system that receives the messages has to be online and reachable from the internet.
- Switch the webhook back on. An Admin can do it under Configure → Webhooks, or your developer can do it through the API.
Until it's switched back on, your other system won't hear about new signatures. Penneo Sign itself keeps working as normal.
Set up a webhook in Penneo (Admins)
- Go to Configure → Webhooks.
- Click Create subscription.
- In URL, enter the HTTPS address where your system receives the events.
- Under Event types, tick the events you want (see the list below). You can search, or tick a whole group like CASEFILE or SIGNER.
- Click Create subscription to save.
To check your setup, click Send test event on the Webhooks page once you have a subscription. On the same page you can view, edit and switch off subscriptions, and see the delivery logs for the last 30 days: which messages were delivered, which failed and why.
Before you start:
- The endpoint must be reachable from the internet. Addresses on your own computer or internal network (like localhost) don't work.
- Test first with a free tool like Webhook.site, and subscribe to the test event
webhook.subscription.test.
Don't see Webhooks under Configure? Only Admins can manage webhooks. Other users see "You don't have access to view this page". Ask an Admin in your company to set it up, or to give you Admin rights.
Set up a webhook with the API (developers)
Create a subscription with a POST request:
POST https://app.penneo.com/webhook/api/v1/subscriptions
{
"eventTypes": ["sign.casefile.completed", "sign.signer.signed"],
"endpoint": "https://example.com/webhook"
}You can use any of Penneo's supported ways to log in to the API. The answer includes a secret that you use to check that messages really come from Penneo. Keep it safe.
You can also list, update, delete and test subscriptions through the API. Full reference, examples and a Postman collection: Webhooks on developer.penneo.com and Postman collection for Penneo Webhooks. To log in to the API, see Generating OAuth 2.0 Client Credentials.
You can have up to 5 active subscriptions per account. Need more? Contact support.
Events you can subscribe to
One subscription can include several events. Messages cover all case files in your account, also those created by your colleagues.
Case file events
| Event | When it's sent |
|---|---|
sign.casefile.completed |
Everyone has signed, and the signed documents are ready to download. |
sign.casefile.expired |
The case file expired before everyone signed. |
sign.casefile.rejected |
One or more signers rejected the signing request. |
sign.casefile.failed |
Something went wrong on Penneo's side. Contact support. |
Signer events
| Event | When it's sent |
|---|---|
sign.signer.requestActivated |
The signer can sign now: the case file was activated, or it's their turn. |
sign.signer.requestSent |
The first signing request email was sent. |
sign.signer.reminderSent |
A reminder email was sent. |
sign.signer.requestOpened |
The signer opened the signing request email. |
sign.signer.opened |
The signer opened the signing page. |
sign.signer.signed |
The signer signed. |
sign.signer.rejected |
The signer rejected the signing request. |
sign.signer.finalized |
The case file this signer belongs to is finalised. |
sign.signer.deleted |
The signer was removed from the case file. |
sign.signer.undeliverable |
Penneo can't send emails to the signer. Check their email address. |
sign.signer.transientBounce |
An email to the signer bounced for now. |
sign.signer.signedWithImageUploadAndNAP |
The signer signed with image upload and NAP (only if your signing flow uses it). |
Test event
| Event | When it's sent |
|---|---|
webhook.subscription.test |
When you trigger a test, to check that your endpoint receives messages. |
Some signer events, like requestSent, opened and signed, can come more than once if a signer signs in several rounds.
What a message contains
Messages are short on purpose. They tell you what happened and the ID of the case file or signer, for example:
{
"topic": "casefile",
"eventType": "completed",
"eventTime": { "date": "2026-01-01 12:59:59.000000", "timezone_type": 3, "timezone": "UTC" },
"payload": { "id": <case file ID>, "status": <status code> }
}To get more details, such as the signers or the signed documents, use the ID to fetch the case file through the API. To read case files created by colleagues, the API user needs access to them.
Make your endpoint reliable
- Answer quickly. Your system must accept the connection within 500 ms and reply within 1.5 seconds. Save the message and reply with a 2xx status straight away, then do the work afterwards.
- Only 2xx counts as delivered. Any other answer, or no answer, makes Penneo try again.
-
Expect duplicates. Each message has a unique
X-Event-Idheader. Remember the IDs for a while and skip any you've already handled. -
Check the signature. Each message has an
X-Event-Signatureheader, signed with your subscription's secret (HMAC-SHA256). We strongly recommend checking it. See how to verify the signature.
When delivery fails, Penneo tries again 5 times within the first minute or so, then once an hour for 30 hours. If none of these work, Penneo switches the subscription off and emails the person who created it and all Admins. Fix the endpoint, then switch the subscription back on.
Using the old webhook service?
Penneo's old webhook service stops on 30 November 2026. If your integration still uses it, move to the webhooks described in this article before then. See the migration guide. Not sure? Ask your software provider or developer.
Still stuck?
Use the chat. Our support team can help with webhooks, the API and your integration.
You can also open the chat any time with the chat button in the bottom right corner.