Webhooks
Webhooks allow you to subscribe to changes on an entity. Currently we only support webhooks on Document Pack changes.
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 Event | Description |
---|---|
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 2 years ago