Callbacks

With the Dropbox Forms API you can use callbacks to be notified about certain events. Currently we support a callback to be registered when a step is started, a form is completed, a workflow is cancelled, or a workflow is completed.

The callback URL will be called according to the following:

curl -X POST https://your.domain.com/some/path
     -H "X-HelloWorks-Signature: {signature}"
     -H "Content-Type: application/json"
     -d "{payload}

Verifying Callbacks

Each callback can be verified by using the signature in the X-Helloworks-Signature request header. This signature is a base16-encoded, SHA-256 hash of the request payload. By itself, this acts as a checksum to detect error in the data.

Additionally, you can upload an RSA public key that we will use to encrypt this hash. This provides an additional layer of assurance that the callback originated from Dropbox Forms. The RSA public key can be set in the Dropbox Forms Portal by editing your Team Settings.

📘

NOTE

Because we use your RSA public key to encrypt the hash, it's possible that other parties have access to this key. Therefore, the key is only useful as a way of confirming the callback's origin if it is protected and unique. We recommend using a unique RSA key that is only shared with Dropbox Forms for the purpose of encrypting the callback signature. This ensures that you can more confidently trust the source and data integrity of the requests you receive.

Generate an RSA key pair

If you don't already have an RSA key pair, you can generate a new one with OpenSSL. Make sure it is installed and follow the steps below.

1. Generate a 4096-bit RSA key pair by pasting the following into a terminal.
2. Export the public key to a file.
3. Copy the public key to your clipboard.
4. Paste the public key into the "Callback Encryption" field and click "Save."

openssl genrsa -des3 -out helloworks.pem 4096

openssl rsa -in helloworks.pem -outform PEM -pubout -out public.pem

pbcopy < public.pem

openssl genrsa -des3 -out helloworks.pem 4096

openssl rsa -in helloworks.pem -outform PEM -pubout -out public.pem

clip < public.pem

openssl genrsa -des3 -out helloworks.pem 4096

openssl rsa -in helloworks.pem -outform PEM -pubout -out public.pem

sudo apt-get install xclip
xclip -sel clip < public.pem

# Tip: If xclip isn't working, you can locate the hidden .ssh folder, open the file in your favorite text editor, and copy it to your clipboard.

Verifying a Callback Signature

To verify your callback:

1. Hash the POST payload using the SHA-256 algorithm and base16-encode the result.
2. If you have uploaded an RSA public key, base64-decode the X-Helloworks-Signature header value and decrypt the decoded string with your RSA private key.
3. Compare the two hashes and make sure they match.

Callback Payloads

Workflow Step Start

Whenever a workflow step is started, a workflow step start callback will be sent to the callback URL.

{
  "type": "signer_step_started",
  "mode": "live|test",
  "action_url": "{view_inst_url}",
  "id": "{workflow_instance_id}",
  "workflow_id": "{workflow_id}",
  "step_id": "{step_id}",
  "role": "{step_role}",
  "signer": "email|phone",
  "metadata": {"tracking_id": "4803294032", "account_id": "1234"}
}

Form Complete Callback

If the customer is allowed to receive the form completion callback, whenever a form is completed, a form complete callback will be sent to the callback URL. As a participant can navigate back through forms, a callback for the same form may be received multiple times.

{
  "type" : "form_completed",
  "id": "{workflow_instance_id}",
  "workflow_id": "{workflow_id}",
  "mode" : "live|test",
  "timestamp" : "{time completed}",
  "step_id" : "{step_id}",
  "role" : "role",
  "signer": "{email or phone of participant}",
  "form_id" : "{form_id},
  "form_name" : "{form_name}",
  "metadata": {"tracking_id": "4803294032", "account_id": "1234"}
}

Workflow Completion Callback

Whenever a workflow is completed, a workflow completion callback will be sent to the callback URL.

{
  "type" : "workflow_stopped",
  "id": "{workflow_instance_id}",
  "workflow_id": "{workflow_id}",
  "status": "completed|error",
  "mode" : "live|test",
  "audit_trail_hash": "{hash}",
  "document_hashes": {
    "{document_id}": "{hash}"
  },
  "data": {
    "{document_id}": {
      "{field}": "{value}"
    }
  },
  "metadata": {"tracking_id": "4803294032", "account_id": "1234"}
}

Workflow Cancellation Callback

Whenever a workflow is cancelled, a workflow cancellation callback will be sent to the callback URL.

{
  "type": "workflow_cancelled",
  "mode": "live|test",
  "id": "{workflow_instance_id}",
  "workflow_id": "{workflow_id}",
  "status": "cancelled",
  "data": {
    "{document_id}": {
      "{field}": "{value}"
    }
  },
  "participants": {
    "name" : "{name}",
    "value" : "{email}|{phone}",
    "status" : "active|waiting|resuming|completed",
    "last_active" : "{date_participated}"
  },
  "metadata": {"tracking_id": "4803294032", "account_id": "1234"}
}