Webhooks & Callbacks
Introduction
In Addo Sign you can define various webhooks. These will send various callbacks as a result of some operation. You define webhooks either on an account level, template level or on an individual request to the Addo Sign Webservices/API.
Initializing webhooks
When creating a signing using either the Addo Sign GUI or the WebServices/API the webhooks to be used is found by following this algorithm:
- (WebServices/API) Look for any webhooks on the request and use them.
- Use webhooks defined on the template.
- Use webhooks defined on the account.
This way, it’s possible to have the “Completed” webhook defined on the account, the “Document opened” webhook defined on the template and the “Document signed” in the request. All three callbacks will be sent.
When you define a webhook, the maximum length of your webhook will be 1000 characters. You can include your own parameters as in:
https://your-domain/your-path?param1=hello¶m2=world
Once a webhook is set on a signing it cannot be changed. If you inherit webhooks from the account and you change the webhook on the account this change will not propagate to signings created before the webhook change on the account.
Parameters
The various webhooks may include certain Addo Sign parameters. These will be added to the URL you supply. Addo Sign reserves these parameter names:
| Parameter | Description |
|---|---|
| signingToken | This is the ID of the signing. This is the value you get back from the /InitiateSigning method in the Webservices. You can also find this value on any signing in your WebAdmin overview by clicking on the Signing Details of a signing. |
| transactionToken | The ID of a recipient. Can be lifted out of the /GetSigning method in WebServices. |
| externalDocumentId | This is an optional ID supplied by you when you created the signing using /InitiateSigning. |
| refNumber | This is an optional reference number supplied by you to the /InitiateSigning method. |
| transactionStateId | The state of the transaction: (-1) Failed: something went wrong. The transaction is not alive. (1) Created: the transaction has been accepted by Addo Sign. (2) Pending: a transaction will be in this state when waiting. F.ex. a signer in the first group will be started (3) and a signer in the second group will be pending (2). (3) Started: the transaction is active and waiting for the signer to come by and sign. (4) Signed: the transaction is signed. (5) ReadyForDistribution: the transaction is about to being distributed. (6) Completed: the transaction has been distributed. No more actions can be done. (7) Expired: the transaction has expired. (8) Cancelled: the transaction was cancelled by the sender. (9) DataCollection: the transaction started as a form and is waiting for the respondent to come by and fill it out. (10) Rejected: the transaction was cancelled by the recipient. (11) Initiating: internal to Addo Sign (Mail merge). (12) InitiatingPending: internal to Addo Sign (Mail merge). (13) WaitingForWitness: the transaction is waiting on witnesses to witness the signing. |
| signingId | This is the Id from our new API /api/v1. In a period of time it will be sent together with signingToken but will eventually replace signingToken. |
| recipientId | This is the transaction Id from our new API /api/v1. In a period of time it will be sent together with transactionToken but will eventually replace transactionToken. |
If you add, e.g., signingToken as a parameter in a webhook, Addo Sign will overwrite this.
Not all webhooks will include all parameters. In the description below, it will be noted which parameter is sent with which webhook.
Please note that in a short period of time you will receive (signingToken + transactionToken) and (signingId + recipientId). The latter pair will eventually replace the former pair.
WebServices and Next Generation API
WebServices
Webhooks are placed in the Callbacks-list property to /Initiate*-methods. Each webhook is put in a callback structure:
{
"Url": [string],
"Type": [int]
}
If you supply an empty string ("") in a webhook it will basically disable that webhook. The omission of a webhook or setting a webhook to NULL will make the algorithm fall-thru to the template and possible account webhooks.
Next Generation API
Webhooks are placed in the callbacks-list property to the "Create Signing" method. Each webhook is put in a callback structure:
{
"url": [string],
"type": [int]
}
If you want to disable a webhook in the next generation API you must supply the type but supply null for URL, such as in:
{
"url": null,
"type": 1
}
Types of webhooks
| Callback | Type |
|---|---|
| Completed | 1 |
| Expiration | 2 |
| Rejection | 3 |
| DocumentOpened | 4 |
| DocumentSigned | 5 |
| TransactionStateChanged | 6 |
| Redirect | 7 |
| Invitation | 8 |
| Reminder | 9 |
| BouncedDelivery | 10 |
| Cancelled | 11 |
| DocumentGroupRejected | 12 |
In the description below, signer is used to denote a signer, a respondent or a recipient.
Completed (type 1)
Parameter: signingToken, signingId
This webhook is signalled when all signers have signed and Addo Sign has collected all evidence and packaged the resulting documents. At this point, you can fetch a copy of the signed document.
The signing is completed and the signing will be anonymized after 40 days.
Expiration (type 2)
Parameter: signingToken, signingId
The signing reached its end date and is expired. The signing will be anonymized after 40 days. In the meantime, if needed, you can re-activate the signing.
Rejection (type 3)
Parameter: signingToken, signingId
Is signalled when a signer cancels the signing.
DocumentOpened (type 4)
Parameters: signingToken, signingId, recipientId, transactionToken, externalDocumentId, fileId
Is signalled when a signer opens / reads a document in the Addo Sign portal.
DocumentSigned (type 5)
Parameters: signingToken, signingId, recipientId, transactionToken, externalDocumentId, fileId
Is signalled when a signer signs a document in the Addo Sign portal. You cannot download the signed document here. Wait on the Completed signal.
TransactionStateChanged (type 6)
Parameters: signingToken, signingId, recipientId, transactionToken, transactionStateId, referenceNumber
This is kind of a debug webhook. You will learn a lot about your transaction. Be prepared to handle the load.
You will never hear about transaction states 11 (Initiating) and 12 (InitiatingPending) though.
Redirect (type 7)
Parameters: signingToken, signingId, recipientId, transactionToken
When the signer has signed or rejected the signing then instead of being shown the Addo Sign receipt page, Addo Sign can redirect the signer to the redirect url. That way, you can proceed with the signer in your workflow on your side.
Invitation (type 8)
Parameters: signingToken, signingId, recipientId, transactionToken
When Addo Sign needs to invite a signer into signing a callback can be sent instead to you. You must do the invitation, Addo Sign will not do anything here.
Reminder (type 9)
Parameters: signingToken, signingId, recipientId, transactionToken
When Addo Sign needs to remind a signer into signing a callback can be sent instead to you. You must do the reminding, Addo Sign will not do anything here.
BouncedDelivery (type 10)
Parameters: signingToken, signingId, recipientId, transactionToken, referenceNumber, errorCode
Is signalled if an e-mail delivery fails and the e-mail bounces. Depending on the receiving e-mail system this notification may or may not be sent. Addo Sign is not in control of that.
Cancelled (type 11)
Parameter: signingToken, signingId
Is signalled when the owner of the signing cancels the signing.
DocumentGroupRejected (type 12)
Parameter: signingToken, signingId, documentGroupId
Is signalled if a signer rejects a document group.
Handle callbacks
You should observe the following when handling callbacks on your side:
- All callbacks are sent using a GET request. You can have us pass a login or even a certificate but that must be set on the account-level and will be done for all callbacks.
- Callbacks will not be sent out of order. For example, you will not receive a Completed callback before a DocumentSigned callback.
- If your handler doesn’t reply with a HTTP status-code 200, Addo Sign will queue the callback until the signing expires using the following algorithm:
- Retry after 1 hour, if it fails,
- Retry after 2 hours after that (3 hours later), if it fails,
- Retry after 3 hours after that (6 hours later), if it fails,
- Retry after 4 hours after that (10 hours later), and so on