Webhooks & Callbacks

Quik! notifies your application of form events—such as a form being submitted or an e-signature envelope being created—by posting data to URLs you control. This guide explains how to register those callback URLs, handle the payloads, and run callbacks inside authenticated environments.

What it is

A callback URL is an endpoint on your own server or application that the Quik! Forms Engine posts to when a specific event happens in a hosted Quik! form. Rather than polling Quik! for status, you give Quik! a URL and Quik! delivers the event data to it.

Quik! supports callbacks for several form events, each configured with its own property:

The most common use case—and the one with the richest configuration—is the e-sign callback (the "Callback Model"), which lets you start a DocuSign signing flow directly from a Quik! form without calling the DocuSign APIs yourself to kick it off. This pattern was designed for environments such as Salesforce, where it is difficult or impossible to intercept the form's POST in order to call DocuSign directly.

Note: All of the e-sign callback configuration below is specific to the DocuSign ESignType object. It is not available for other e-signature integrations.

How the e-sign Callback Model works

When you configure a SignCallBackURL, the flow is:

1. The user clicks the Sign button, which opens the Quik! form's e-sign pop-up.
2. The user enters envelope data and clicks Send. The Send event posts the form data directly to Quik! at https://websvcs.quikforms.com/rest/esignature/docusign/sign.
3. Quik! looks up your stored DocuSign OAuth token and calls the DocuSign REST API to start the envelope.
4. DocuSign responds with the EnvelopeID. Quik! stores it alongside the form's QFVUNID for later retrieval as a backup.
5. Quik! returns the EnvelopeID to the form (in the HTML viewer) in JSON format.
6. The form posts the EnvelopeID—plus any status message from the signing process—to your SignCallBackURL in JSON format.
7. Your SignCallBackURL responds in JSON with a status message that the form displays to the user.

Note: This flow starts the signing process only. To check envelope status or download the final signed document, you still call the DocuSign APIs yourself. This assumes you already have a DocuSign account and have set up a DocuSign OAuth token with Quik!.

Prerequisites for the e-sign callback

To use the e-sign Callback Model you must set up these components:

1. Create a DocuSign OAuth token in the Quik! App. This stores your DocuSign credentials with Quik! so Quik! can call DocuSign on your behalf. You only need to do this once per CustomerID, CustomerUserID, and DocuSign environment.
2. Configure a Forms Engine request containing the DocuSign token and environment details in the ESignType object.
3. Stand up a callback endpoint on your application or server to receive the EnvelopeID.
4. Assign your endpoint to the SignCallBackURL property within the ESignType object.

Configuring an e-sign callback URL

Set the e-sign callback properties inside the ESignType object of your Forms Engine request. A minimal DocuSign callback configuration looks like this:

{
  "HostFormOnQuik": true,
  "QuikFormID": "12",
  "PrintEditablePDF": true,
  "FormFields": [
    { "FieldName": "1own.FName", "FieldValue": "John" },
    { "FieldName": "1own.LName", "FieldValue": "Doe" },
    { "FieldName": "1own.H.Email", "FieldValue": "JohnDoe@test.com" }
  ],
  "ESignType": {
    "Type": "docusign",
    "AuthUserID": "<YourAuthUserID>",
    "SignCallBackURL": "<YourCallbackURL>",
    "SignEnvironmentID": 2
  }
}

E-sign callback properties

Note: When SignCallBackURL is set, the Forms Engine automatically sets the SignURL value to https://websvcs.quikforms.com/rest/esignature/docusign/sign, even if you set SignURL yourself.

Setting the callback content type

Use the SetContentTypeCallBackURL property (inside the DocuSign ESignType object) to control how the callback request body is formatted so your server can parse it. If you don't set it, the default is 0 (JSON).

For REST (and VB) implementations, use the integer values shown above. Example:

{
  "HostFormOnQuik": true,
  "QuikFormID": "1",
  "ESignType": {
    "Type": "Docusign",
    "AuthUserID": "Test",
    "SetContentTypeCallBackURL": 2,
    "SignCallBackURL": "https://www.google.com",
    "SignEnvironmentID": 2
  }
}

Note: SetContentTypeCallBackURL is available only for the DocuSign integration, not for other e-signature integrations.

Handling the callback payload

When your endpoint receives the EnvelopeID, it must respond to the form in JSON. The form uses your response to decide what message to show the user:

{
  "StatusCode": 0,
  "StatusMessage": "200 (ok)",
  "Message": "Your form has been submitted for signature. Each recipient will receive an email to begin the signature process. Check your email for signature updates."
}

How the form interprets your response:

Using the hosted callback endpoint

If you don't need to do anything with the returned EnvelopeID yourself (for example, you won't check status or download documents independently), you can point SignCallBackURL at Quik!'s hosted endpoint instead of building your own. It simply returns a message that the envelope has been started.

https://websvcs.quikforms.com/rest/ESignature/callbackurl

Use this URL at your discretion.

Retrieving the Envelope ID from a hidden form field

By default, every Quik! HTML form includes a hidden field that is populated with the new DocuSign EnvelopeID once the user clicks Send in the e-sign pop-up. You can read this value with a custom function in the ESignVendorSuccessJavaScript property—useful if you want to capture the EnvelopeID client-side rather than (or in addition to) handling it on your callback endpoint.

When you provide any value for ESignVendorSuccessJavaScript, the default success alert messages are suppressed. If you still want to show a message, include it in your function.

{
  "HostFormOnQuik": true,
  "QuikFormID": "12",
  "ESignType": {
    "Type": "DocuSign",
    "CreateEnvelopeAsDraft": true,
    "SkipESignPopup": true,
    "AuthUserID": "<your AuthUserID>",
    "SignCallBackURL": "<your SignCallBackURL>",
    "SignEnvironmentID": <your SignEnvironmentID>,
    "ESignVendorSuccessJavaScript": "function(){var id = $('#ESignTransactionID').val(); console.log('done signing!. EnvelopeID is ' + id);}"
  }
}

Replace the console.log call with whatever your application needs to do with the EnvelopeID. The example uses jQuery, but plain JavaScript works too.

Authenticated callbacks (e.g. Salesforce)

In password-protected environments such as Salesforce, posting directly to a REST endpoint for the callback URL can hit authentication issues. In Salesforce, you typically create a REST endpoint for the callback URL. To work around the authentication barrier, use a Salesforce Remote Action call instead—a mechanism that exposes Apex controller methods to JavaScript, bypassing the authentication issues that block a plain HTTP POST.

The approach is:

1. Expose the method you want the callback to reach as a Salesforce Remote Action.
2. Have the callback invoke that JavaScript method rather than posting to a URL.
3. Perform a find-and-replace on the string returned from the Quik! web service to rewrite the callback so it calls your JavaScript method instead of sending an Ajax callout.

Because Remote Action signatures and the exact callback string vary by Salesforce org and Quik! Forms Engine version, work from the values your own configuration returns rather than a fixed template. For the current request and response shapes, see the Notifications and Webhooks API reference. If you need help mapping the find-and-replace to your environment, contact Quik! support.

Optional: combining submit and sign

You can change how the e-sign Send button behaves relative to your Submit handling. Both SignSubmitCombined and SignSendJavascript are top-level properties of the Forms Engine request—set them as siblings of ESignType, HTMLButtonSubmit, and HTMLButtonSign, not inside ESignType.

• Set SignSubmitCombined to true so that clicking Sign first fires the Submit event—validating required fields and posting to your SubmitURL—before opening the e-sign pop-up and starting the signature process. Required-field validation runs, but a failed validation will not stop the signature process when using the default Submit JavaScript.
• Alternatively, set SignSendJavascript to a JavaScript string to override the default JavaScript that runs when the user clicks Send in the e-sign pop-up.

A complete SignSubmitCombined request looks like this:

{
  "HostFormOnQuik": true,
  "QuikFormID": "12",
  "HTMLButtonSubmit": {
    "title": "Submit",
    "submitContentType": "Json",
    "show": true,
    "name": "Submit",
    "submitURL": "<YourSubmitURL>"
  },
  "HTMLButtonSign": {
    "title": "Sign",
    "show": true,
    "name": "Sign",
    "signContentType": "Json"
  },
  "SignSubmitCombined": true,
  "ESignType": {
    "Type": "docusign",
    "AuthUserID": "<YourAuthUserID>",
    "SignCallBackURL": "<YourCallBackURL>",
    "SignEnvironmentID": 2
  }
}

When the user clicks Sign, the submit event fires first to validate any required fields and post the data to your SubmitURL, then the e-sign pop-up opens so the user can enter signer information and send the forms for signature.

Legacy SOAP callbacks (deprecated)

Note: The SOAP web services below are deprecated and no longer in use. They are documented here for reference only. Use the REST configuration described above for new integrations.

In the legacy SOAP Forms Engine, you enabled the Callback Model by setting SignCallBackURL inside an ESignType element typed as ESignTypeDocusign:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthenticationHeader xmlns="https://websvcs.quikforms.com/quikformsenginews/">
      <CustomerID>YOUR CUSTOMER ID</CustomerID>
      <UserName>YOUR USERNAME</UserName>
      <Password>YOUR PASSWORD</Password>
    </AuthenticationHeader>
  </soap:Header>
  <soap:Body>
    <Execute xmlns="https://websvcs.quikforms.com/quikformsenginews/">
      <QFESettings>
        <HostFormOnQuik>true</HostFormOnQuik>
        <QuikFormID>1</QuikFormID>
        <ESignType xsi:type="ESignTypeDocusign">
          <SignCallBackURL>https://google.com</SignCallBackURL>
          <SignEnvironmentID>2</SignEnvironmentID>
        </ESignType>
      </QFESettings>
    </Execute>
  </soap:Body>
</soap:Envelope>

The legacy DocuSign Callback web service exposed two methods that accept the raw posted form data and return the EnvelopeID:

Both accept a single FormData string parameter (the form POST data, max 8000 characters).

Related articles

• Saving forms
• Send direct to DocuSign
• Forms Engine API reference
• Notifications and Webhooks API reference