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.