Callbacks on the API v.1

The API offers two types of callback, or 'webhooks'. We recommend you use these callbacks and not polling.

1. Option 1 ('all') - Everything every 6 minutes; or

2. Option 2 ('signed') - a notification when a document is signed.

Option 1. Everything every 6 minutes.

Data is POSTED to you in two sections, 'data’ and 'signed’. The data section is a JSON object that is a list of dictionaries of the changes. The dictionaries are a record of each change to document and signer status in the order they occured. The second section is a signed string (base64 encoded) you can use to verify the data is genuine should you wish. Contact us for the X509 certificate.

The data contains a list of dictionaries that contains the notification information.

Example:

 {
    u'data':
        [
          u'[
                {
                "timestamp": "2018-03-20T07:09:52",
                "name": "status",
                "value": "40",
                "resource_uri": "/api/v1/signer/[signer-id]/"
                },
                {
                "timestamp": "2018-03-20T07:09:52",
                "name": "status", "value": "30",
                "resource_uri": "/api/v1/document/[doc-id]/"
                }
            ]'
        ],
    u'signed':
        [u'long_string_of_numbers_and_digits']
    }

This tells you that signer "/api/v1/signer/[signer-id]/" 
changed to status 40 (signed) at 2018-03-20T07:09:52, and 
that document '/api/v1/document/[doc-id]/' was fully signed (status 30) 
at 2018-03-20T07:09:52. (A signed document has status 30, while a signed 
signer has status 40.) The dictionary will contain each status change 
in order they occured with the timestamp, so it is likely to contain multiple status changes 
for a single signer.

This tells you that signer "/api/v1/signer/[signer-id]/" changed to status 40 (signed) at 2018-03-20T07:09:52, and that document '/api/v1/document/[doc-id]/' was fully signed (status 30) at 2018-03-20T07:09:52. (A signed document has status 30, while a signed signer has status 40.) The dictionary will contain each status change in order they occured with the timestamp, so it is likely to contain multiple status changes for a single signer.

Combine your callback with an overnight sync. For syncing use the /document/ endpoint and the special query parameter ?cache=1. This is a fast and efficient way to get back the status of all your outstanding documents. See API /document/ endpoint for more information.

Option 2. Realtime update when a document is signed

Example of the POST that will be sent to you:

    {
      "resource_uri": "/api/v1/document/[doc-id]/",
      "group": "/api/v1/group/your-group/",
      "name": "name of doc",
      "uuid": "[doc-id]",
      "tag": "your-tag-if-used"
    }

Whenever a document is signed you’ll get a POST containing the resource URI, group, name of document and its id. This is just a regular POST dictionary, it is not a JSON object.

More accurately, this callback is emitted when the final document is created, so you can reliably use it to trigger a document download.

(If you used the API to create the document in the first place, the status resource_uri of the document is included in the 'Location’ header of the 201 'created’ response.)