Webhooks
Subscribe to topics so that Penneo can notify you when something changes for your case file
Before you start
Please make sure your endpoint is accessible from the internet, localhost won't work.
We suggest you try it setting up the subscription with http://webhook.site/ first, that will eliminate any potential problems on your end.
Besides calling the API directly, you can also use our .Net or PHP SDKs.
1. Create a subscription
You can subscribe to the casefile topic with an endpoint which will be used by Penneo to send notifications.
POST https://app.penneo.com/api/v1/webhook/subscriptions
Authorization: JWT
x-auth-token: <your token>
Accept-charset: utf-8
Accept: application/json
Content-Type: application/json
{
"topic": "casefile",
"endpoint": "<your endpoint>"
}
{
"userId": <your user id>,
"customerId": <your customer id>,
"confirmed": false,
"id": <Subscription ID>,
"topic": "casefile",
"endpoint": "<your endpoint>",
"created": "1535571567"
}
2. Confirm the subscription
As soon as you create the subscription, Penneo will send a token to that endpoint. Use that to confirm the subscription
POST https://app.penneo.com/api/v1/webhook/subscriptions/{subscriptionId}/confirm
Authorization: JWT
x-auth-token: <your token>
Accept-charset: utf-8
Accept: application/json
Content-Type: application/json
{
"token": "<token that you received on your url>"
}
3. Test the subscription
You can test that everything is setup correctly by calling the following endpoint
POST https://app.penneo.com/api/v1/webhook/subscriptions/{subscriptionId}/test
Authorization: JWT
x-auth-token: <your token>
Accept-charset: utf-8
Accept: application/json
Format of the notification
By default, the notification's payload is a JSON object. If the user that owns the subscription doesn't own the case file, then only the id and the status are included in the payload e.g.
{
"topic": "casefile",
"eventType": "rejected",
"eventTime": {
"date": "2018-10-30 12:59:13.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"payload": {
"id": <id>,
"status": <status>
}
}
If you want to get to full payload including the title and other properties, you need to create a super api user. See the section Archiving signed documents for more details.
Authorization
Webhooks work with any supported Authorization method, not just JWT as in the examples above.
Supported subscription topics
Two topics are currently supported: 'casefile' and 'signer'.
The casefile topic is notified for the following events:
- 'completed' - everyone has signed and the finalized PDF documents are ready for download
- 'rejected' - one or more signers have rejected the to sign
- 'failed' - there was an error on our part, this may require contacting support
The signer topic is notified for the following events:
- 'requestActivated' - the signer is ready to sign; either the case file has been activated, or their signing round has just come up
- 'requestSent' - the initial signing request email has been sent out
- 'reminderSent' - a signing reminder email has been sent
- 'requestOpened'' - a singing request email has been opened
- 'undeliverable' - Penneo cannot send the emails to the signer, check the signer's address
- 'opened' - the signer has viewed the signing page
- 'rejected' - the signer has rejected
- 'signed' - the signer has signed
- 'finalized' - the casefile this signer belongs to has been finalized
- 'deleted' - the signer has been deleted
Please note that some events can happen multiple times. For example, a signer that signs in multiple signing rounds will have multiple events of type requestSent
, opened
, signed
, etc.
Common problems
I'm not getting any requests for Penneo
Your endpoint is probably not accessible from the internet, please try it out with http://webhook.site/ and try to rule that out.
I get requests, but there's no confirmation token
Unfortunately, we can't properly set the Content-Type header for these requests, which means your server software might have trouble parsing their bodies.
Updated 3 months ago