Guides

Webhooks

Webhooks allow you to subscribe to changes on an entity. Currently we only support webhooks on Document Pack changes.

Suggest Edits

📘

Subscriptions in V0 of api became webhooks in V1

Migration:
Endpoint url /subscriptions is replaced with /webhooks
Whenever a subscription_key was used/returned, a webhook_key is now used/returned

In the list of constants below, you can find Webhook Callback Events , which lists the callback events.

Callback EventDescription
entity_updated
document_status_changed
final_document_generated		Data on the entity was updated.
Document Status changed
Final pdf document has finished

We will call your URL based on 3 callback events:

  • entity_updated (data on the document entity was updated)
  • document_status_changed (status of the document has changed)
  • final_document_generated (Final pdf document has been generated. This will then be your queue to run a request on "/document_packs/<your_document_pack_key>". Each document in the pack has a "serve_pdf_url" which can be used to download the document.)

Create Webhook

To subscribe to changes on an entity, see the instructions below.
Lets assume we're working on the sandbox environment, the webhook endpoint will be used as follows:
** POST {{url}}/webhooks .
Eg: POST https://sandboxapi.quicklysign.com/v1/webhooks

The JSON body structure for the webhook subscription requires the following:
client_secret - this is your own secure client_secret reflected under your profile.
entity_key - this will be your document_pack key that is returned when creating a document. Use the key property returned in the document object as the entity_key in queries.
callback - this is the callback URL that we will point to when the 3 mentioned processes are fired. QuicklySign will then notify this URL of the actions mentioned. (Please note to not use your localhost when entering in this value, unless you're using a tool somewhat like NGROK to have an https endpoint):
client_id - this is your own secure client_id reflected under your profile.

Request:

{
    "client_secret": "{{client_secret}}",
    "webhook": {
        "entity_key": "ahFzfnF1aWNrbHlzaWduLWRldnInCxIIRG9jdW1lbnQiGWY2VDNXNW9DejVnQWJnMTgyYjYwMDQyZTAM",
        "callback": "https://yourownURL.io/test_callback"
    },
    "client_id": "{{client_id}}"
}

Response:

{
    "status": {
        "status_code": 200
    },
    "data": {
        "webhook": {
            "entity_key": "ahNkZXZ-cXVpY2tseXNpZ24tZGV2chULEghEb2N1bWVudBiAgICAgMDvCww",
            "date_updated": 1401645889795,
            "webhook_key": null,
            "callback": "http://api.127.0.0.1.xip.io:8080/v1/test_callback",
            "key": "ahNkZXZ-cXVpY2tseXNpZ24tZGV2chkLEgxTdWJzY3JpcHRpb24YgICAgIDwiwoM",
            "date_created": 1401645889795
        }
    }
}

Client_id and client_secret are required for all Webhook calls

To test callbacks, subscribe to document changes (using create webhook endpoint), then make changes to the document using the frontend and you will receive a POST on the callback url you specified when you created the webhook.
The callback url must return 200 response on successful call.

Note: Webhooks are currently only supported for document_packs.

📘

Debugging callback events

If you want to see what events were generated and sent to your server you can look at the the logs here callback logs

Example callback responses from QuicklySign:

{
   u'entity_type': u'Document', 
   u'entity_key': u'ahFzfnF1aWNrbHlzaWduLWRldnInCsokPPOSEisjaxxXNSTnQ0MTgyYjY3ODI4N2MM', 
   u'callback_event': u'document_updated', 
   u'subscription_key': u'ahFzfnF1aWNrbHlzaasrRTsaaZCxIMU3Vic2NyaXB0aW9uGICAgOnTvaIJDA'
}

{
    u'entity_type': u'Document'
    u'callback_event': u'signatory_updated', 
    u'subscription_key': u'ahFzfnF1aWNssRSDzaWduLWRldnIZCxIMU3Vic2NyaXB0a73sjiSFHYgOnTvaIJDA', 
    u'entity_key': u'ahFzfns345WffbHlzaWduLWRldnInCxIIRG9jdW1lbnQiGW51kISJAdrbXNSTnQ0MTgyYjY3ODI4N2MM', 
}

{
    u'subscription_key': u'ahFzfnFasr1aWNrbHlzaWd3uLWRldnIZCxIMU3Vic2NyaXB0a2W9uasddgfd5OnTvaIJDA', 
    u'entity_type': u'Document', 
    u'entity_key': u'ahFzfnF1aWNrbHlzWIJ9as8s7wSDRG9jdW1lbnQiGWFiQk5JZ2drbXNsdTT31TgyYjY3ODI4N2MM', 
    u'callback_event': u'audit_trail_updated'
}

{
    u'subscription_key': u'ahFzfSfwnF1aWNrbHlsGDRzaWduLWRldnIZCxIMU3Vic2NyaXB0aW9uG36ICAgOnTvaIJDA', 
    u'entity_type': u'Document', 
    u'entity_key': u'ahFzfnF1asda63GDsWNrbHlzaWduLWRldnInCxIIRG9jdW1lbnQiGWFiQk5JZ2drbXNSTnQsad6543YjY3ODI4N2MM', 
    u'callback_event': u'final_document_generated'
}

A reminder for the above final_document_generated example. (Final pdf document has been generated. This will then be your queue to run a request on "/document_packs/<your_document_pack_key>". Each document in the pack has a "serve_pdf_url" which can be used to download the document.)

Get Webhook

GET
/webhooks/<webhook_key>?client_id=<client_id>&client_secret=<client_secret>

Gets the webhook for the given key

Get Webhooks

Get
/webhooks?client_id=<client_id>&client_secret=<client_secret>

Specify query string parameter entity_key=<subscribed_to_entity_key> and all your webhooks for that entity will be returned. An example of an entity_key would be a document's key. Any changes to the document will trigger a callback.

Unsubscribe by webhook key

Delete
/webhook/<webhook_key>?client_id={{client_id}}&client_secret={{client_secret}}**

Unsubscribe by entity key

Delete /webhook?client_id={{client_id}}&client_secret={{client_secret}}&entity_key={{entity_key}}

Updated over 1 year ago