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.

HTTP Request

POST <<penneo_api_base_url>>/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>"
}

HTTP Response

{
  "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 message to that endpoint:

Webhook message

{
  "Type" : "SubscriptionConfirmation",
  "Token" : <unique confirmation token>,
  ...
}

Use the token to confirm the subscription

HTTP Request

POST <<penneo_api_base_url>>/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>"
}

The response body will be empty.

🚧

Remember to confirm the webhook!

An unconfirmed webhook will not receive any message from Penneo.

3. Test the subscription

You can test that everything is setup correctly by calling the following endpoint

HTTP

POST <<penneo_api_base_url>>/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 and will only include the status and a numerical ID of either the caseFile or the signer.

Casefile update

{
  "topic": "casefile",
  "eventType": "rejected",
  "eventTime": {
    "date": "2023-01-01 12:59:59.000000",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "payload": {
    "id": <int>,
    "status": <int>
  }
}

Signer update

{
  "topic": "signer",
  "eventType": "finalized",
  "eventTime": {
    "date": "2023-01-01 12:59:59.000000",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "payload": {
    "id": <int>,
    "caseFile": { 
      "id": <int>, 
      "status": <int>
    }
  }
}

The webhook will receive notifications about all the caseFiles created in the same account the user belongs to, including caseFiles created by other users, like for example their colleagues.

That means that the owner of the webhooks subscription will not necessarily be able to then fetch further information about a caseFile or a signer unless the caseFile is either shared with them or placed in a shared folder to which the user has access.

If you want to get the 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.

🚧

Watch out

The Content-Type header will always be text/plain; charset=UTF-8 even if the response body is actually a JSON object.

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.

Retries & Failures

Our system implements a retry strategy to enforce the delivery of our notifications to your webhooks.
If your webhook, for any reason, returns a response different than 2xx success or does not return a response at all after 15 seconds, our system will consider it a failed delivery.
It will then retry to send the notification up to 3 times, 20 seconds apart from each other.
After the third failure, the system will drop further notifications to avoid flooding your server.

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.