Your E-sign service has to send web hooks to your app when a recipient interacts with the document.

This could be set up either when the document is created (send endpoint) or on an account or user basis.

It's important that your app knows which Upsales customer id (and user id if the app is user configurable) the webhook is for.

1 Your app receives a webhook from your E-sign service and initiates a manual run with the body you got from the hook: a POST to /api/external/appHook with the query parameters customerId, appId and authenticationKey. Add userId if the app is user configurable; without it the run does not start.

2 Your apps /external endpoint gets a request with the requests body.data containing the web hook data.

3 Update the E-sign document in Upsales: get the esign object from Upsales API using the requests body.apiKey and update it with PUT /esigns/:id according to the webhook information. The request body only contains apiKey if your app is set up to use an API key.

• On each recipient in the involved array, set the date the recipient opened the document (seen), signed it (sign) or declined it (declineDate, with the reason in declineMsg). If the invitation could not be delivered, set undelivered to mail or sms.
• Set state on the document when it is finished: 30 when everyone has signed, 20 when a recipient has declined. The document stays pending (10) until you do.

When state is set to 30, Upsales sets the sign date and moves the linked opportunity to the stage chosen when the document was sent, if the opportunity is still open and the fields required for that stage are filled in.