Overview

Webhooks allow your application to receive real-time notifications when a change occurs on a document pack / child document (entity). Webhooks are are supported for document pack and child document events.

Log Retention

Webhook callback logs are retained as long as the associated document pack exists. If the document pack is deleted, all related webhook logs are removed.

• There is no maximum retention period while the document pack remains active.

Migration from V0 → V1

Webhook Events

When a subscribed event occurs, QuicklySign sends an HTTP POST request to your callback URL with:

• Method: POST
• Header: Content-Type: application/json
• Body: JSON object (raw, not URL-encoded)

Available events (You can find a list of all available events here):

Your webhook endpoint must return HTTP 200 OK to acknowledge receipt.

Delivery Retries & Backoff

QuicklySign automatically retries delivery if your endpoint is unreachable or returns a non-2xx response. Retries use exponential backoff until a successful 200 OK is received.

Create a Webhook Subscription

Endpoint:

POST /v1/webhooks
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

Request Body:

Example Request:

{
  "client_secret": "{{client_secret}}",
  "client_id": "{{client_id}}",
  "webhook": {
    "entity_key": "ahFzfnF1aWNrbHlzaWduLWRldnInCxIIRG9jdW1lbnQiGWY2VDNXNW9DejVnQWJnMTgyYjYwMDQyZTAM",
    "callback": "https://yourapp.com/callback"
  }
}

Example Response:

{
  "status": { "status_code": 200 },
  "data": {
    "webhook": {
      "key": "ahNkZXZ-cXVpY2tseXNpZ24tZGV2chkLEgxTdWJzY3JpcHRpb24YgICAgIDwiwoM",
      "entity_key": "ahFzfnF1aWNrbHlzaWduLWRldnInCxIIRG9jdW1lbnQiGWY2VDNXNW9DejVnQWJnMTgyYjYwMDQyZTAM",
      "callback": "https://yourapp.com/callback",
      "date_created": 1401645889795,
      "date_updated": 1401645889795
    }
  }
}

Note: client_id and client_secret are required for all webhook operations.

Testing Webhooks

1. Create a webhook subscription.
2. Make changes to the document via the QuicklySign dashboard or API.
3. Your callback URL will receive POST requests for subscribed events.
4. Ensure your endpoint returns HTTP 200 OK to acknowledge receipt.

To inspect delivery attempts, please use Webhook Logs.

Example Callback Payloads

Entity Updated

{
  "entity_type": "Document",
  "entity_key": "ahFzfnF1aWNrbHlzaWduLWRldnInCxIIRG9jdW1lbnQiGWY2VDNXNW9DejVnQWJnMTgyYjYwMDQyZTAM",
  "callback_event": "entity_updated",
  "webhook_key": "ahNkZXZ-cXVpY2tseXNpZ24tZGV2chkLEgxTdWJzY3JpcHRpb24YgICAgIDwiwoM"
}

Signatory Updated

{
  "entity_type": "Document",
  "entity_key": "ahFzfnF1aWNrbHlzaWduLWRldnInCxIIRG9jdW1lbnQiGWY2VDNXNW9DejVnQWJnMTgyYjYwMDQyZTAM",
  "callback_event": "signatory_updated",
  "webhook_key": "ahFzfnF1aWNssRSDzaWduLWRldnIZCxIMU3Vic2NyaXB0a73sjiSFHYgOnTvaIJDA"
}

Audit Trail Updated

{
  "entity_type": "Document",
  "entity_key": "ahFzfnF1aWNrbHlzWIJ9as8s7wSDRG9jdW1lbnQiGWFiQk5JZ2drbXNSTnQsad6543YjY3ODI4N2MM",
  "callback_event": "audit_trail_updated",
  "webhook_key": "ahFzfnFasr1aWNrbHlzaWd3uLWRldnIZCxIMU3Vic2NyaXB0a2W9uasddgfd5OnTvaIJDA"
}

Final Document Generated

{
  "entity_type": "Document",
  "entity_key": "ahFzfnF1asda63GDsWNrbHlzaWduLWRldnInCxIIRG9jdW1lbnQiGWFiQk5JZ2drbXNSTnQsad6543YjY3ODI4N2MM",
  "callback_event": "final_document_generated",
  "webhook_key": "ahFzfSfwnF1aWNrbHlsGDRzaWduLWRldnIZCxIMU3Vic2NyaXB0aW9uG36ICAgOnTvaIJDA"
}

After receiving final_document_generated, fetch the full document pack:

GET /v1/document_packs/{document_pack_key}

Download final PDFs via each document’s serve_pdf_url.

Get a Webhook

GET /v1/webhooks/{webhook_key}?client_id={{client_id}}&client_secret={{client_secret}}

Fetch details for a single webhook subscription.

List Webhooks

GET /v1/webhooks?client_id={{client_id}}&client_secret={{client_secret}}

Optional query parameter:

Delete / Unsubscribe Webhooks

By Webhook Key

DELETE /v1/webhooks/{webhook_key}?client_id={{client_id}}&client_secret={{client_secret}}

By Entity Key

DELETE /v1/webhooks?client_id={{client_id}}&client_secret={{client_secret}}&entity_key={{entity_key}}

FAQ

1. What should my webhook endpoint return?

Only a 2xx HTTP status is required. No JSON body is necessary.

2. Do webhook logs show failure details?

Yes. The log field shows the action taken and any errors returned by your endpoint.

3. How are webhook logs ordered?

Logs are chronological: oldest first, newest last.

4. What format are webhook requests sent in?

Webhook requests are sent as:

• HTTP POST requests
• A raw JSON body
• With the header Content-Type: application/json