Articles on: API Documentation

WaiverSign API: Handling Callbacks

When you create a signing session with a callbackUrl, WaiverSign sends a POST request to that URL each time a participant completes signing. This lets your application receive signed waiver data in real time without needing to check back or poll the API.

Setting Up a Callback

Include a callbackUrl when you create a signing session:
json

{
  "documentIdList": ["5afba2484fa1da256ed15c7c"],
  "personInfoList": [{"isAdult": true}],
  "callbackUrl": "https://www.yoursite.com/api/waiver-callback"
}

The callback URL must be a server-side endpoint capable of receiving HTTP POST requests. A static page or client-side JavaScript will not work.

Callback Payload

When signing is complete, WaiverSign POSTs a JSON payload to your callback URL containing the signer's submitted data and details about each signed document.
json

{
  "personInfoList": [
    {
      "firstName": "Jennifer",
      "lastName": "Highland",
      "nickName": "Jenn",
      "middleName": "Rose",
      "title": "Mrs.",
      "gender": "FEMALE",
      "email": "jennifer@example.com",
      "birthDate": "03/09/1992",
      "streetAddress": "123 Main Street",
      "city": "Salt Lake City",
      "postalCode": "84123",
      "organization": "Jenn's Fresh Market",
      "entityId": "5c4e9e7f4a67ce551cccb425",
      "checkId": "0fee875b-3dda-4578-9caf-b9d9d26eb780",
      "isGuardian": true,
      "sendEmail": false,
      "createdBy": "jennifer highland"
    }
  ],
  "documentList": [
    {
      "name": "Liability Waiver",
      "signedDate": "2025-01-22T00:15:45.120Z",
      "id": "6t0a09426a110800120b9b65",
      "signedWaiverId": "a7d7tt39-347b-4mqd-9065-d92ct121bf2c",
      "signedWaiverKey": ";uV1PC6!0N"
    }
  ],
  "callbackUrl": "https://www.yoursite.com/api/waiver-callback"
}

Person Fields

The personInfoList in the callback includes all the data the signer submitted on the form, plus several fields generated by WaiverSign:

Field	Description
entityId	WaiverSign's unique identifier for this signer
checkId	Unique identifier for this specific signing instance
isGuardian	`true` if this person signed as a guardian for one or more minors in the session
sendEmail	Whether an email notification was sent to this signer
createdBy	Display name of the person who signed
All standard person fields (name, email, phone, address, custom fields, identification) are also returned with whatever values the signer entered on the form.

Document Fields

Each entry in documentList represents one signed document:

Field	Description
name	The document title as configured in WaiverSign
signedDate	UTC timestamp of when the document was signed (e.g., `"2025-01-22T00:15:45.120Z"`)
id	The original document template ID
signedWaiverId	Unique ID for this specific signed copy of the waiver
signedWaiverKey	Key associated with the signed waiver

Things to Know

One callback per signing session. If the session includes multiple documents, you receive a single callback with all signed documents listed in the documentList array.
The callbackUrl is included in the payload. This is useful if your application uses different callback URLs for different session types and needs to confirm which one was used.
Store the signedWaiverId. If you need to reference a specific signed waiver later, the signedWaiverId is the unique identifier for that signed copy.
Person data reflects what was submitted, not what was pre-populated. If the signer changed a pre-filled value on the form, the callback contains the updated value.

Updated on: 06/24/2026

Was this article helpful?

Thank you!