Best practices for Dropbox Sign callbacks

The Sign API sends callbacks, also known as webhooks, for the life cycle of a signature request. You can listen for these callbacks to build a reliable flow in your application.

After you call the signature_request/create_embedded or signature_request/create_embedded_with_template endpoint to create your signature request, you get back a 200 status and JSON response from the API.

This gives you the basic information you need about the request, and lets you know that our server received it successfully and there were no issues with the parameters you passed in:

However, here is what's happening behind the scenes:

1. The request hits our server.
2. Sign API returns a 200 status.
3. The document is converted and field overlay is created.

There are times that there are issues in this last conversion step, particularly if you're using text tags or templates, as the information passed in through the API call may not match the document during the overlay. For example, if your document has a text tag on it assigned to signer3, but you have only passed in two signers, this is flagged as an error.

This is why it is best practice to wait for the signature_request_sent callback before calling embedded/sign_url to open the iFrame - signature_request_sent only fires once conversion and overlay processes are complete. In the case of an error during conversion, a file_error or signature_request_invalid callback will be sent instead, depending on the reason. See this list for all possible callback events.

When a signature request is opened in the iFrame, a signature_request_viewed callback is fired and lets you know who viewed the document and when.

The signature_request_signed callback fires after each signer completes the request, and the signature_request_downloadable callback lets you know that a signer’s information has been added to the document and it is ready for download in its current status.

A final best practice is to wait for the signature_request_all_signed callback before calling the signature_request/files endpoint. This ensures that you will get the final copy of the document with all signatures and the completed status on the audit trail.

Related resources

• Example Dropbox Sign API Callback Event
• The difference between signature_request_signed and all_signed callback events.
• Example Java Callback Handler
• Simple PHP Callback Handler
• A Simple Python Callback Handler
• Example of how to use ngrok (or other localhost tunneling software) to test callback handlers
• Tools for testing the API and Callbacks locally