AuthorizationThis section covers a REST-integration. For the authorization you need the OrganizationKey and the UserLoginName of your organization. You can find this two keys in Settings->Organization. If you are authorized you will get a HTTP/200 Ok info. Otherwise you will get a 401 Unauthorized error. CallbacksThe API allows the definition of several callbacks. Please note, that only the envelope callback (directly from eSignAnyWhere) is fired, when the envelope is in a final state. The status update callback is fired by a sub-component and you may require to wait a post-processing time that the envelope reaches its final state. Info |
---|
Detailed callbacks on specific events
Note: You can configure a proxy for all callbacks. Please see the next sample: Code Block |
---|
| <callbackProxySettings>
<!-- Enable or disable the use of proxy for all callbacks. Values 1 (enabled) or 0 (disabled)-->
<enabled>0</enabled>
<!-- Address of the proxy server-->
<address></address>
<!-- Send all callbacks to local addresses without using proxy. Values 1 (bypass for local) or 0 (always use proxy)-->
<!-- Local requests are identified by the lack of a period (.) in the URI, as in http://webserver/, or access the local server, including http://localhost, http://loopback, or http://127.0.0.1-->
<bypassProxyOnLocal>0</bypassProxyOnLocal>
<networkCredentials>
<!-- Domain for Credentials-->
<domain></domain>
<!-- Username for Credentials-->
<username></username>
<!-- Password for Credentials. If password is not encrypted then remove the attribute enc-->
<password enc="sec2"></password>
</networkCredentials>
</callbackProxySettings> |
|
Envelope CallbackThis is the basic callback (“CallbackUrl”: “”), which is fired if the envelope reaches a final state (completed, rejected). If you integrate eSAW, please have a look at the Envelope Status Callback (directly below documented), because it might deliver more details about the envelope and might so be more useful for integrating. Placehoder - ##EnvelopeId##
- ##Action##
- envelopeFinished : when an envelope was finished (completed or rejected)
Sample: https://www.mycallback.at?envelope=##EnvelopeId## Envelope Status CallbackEnvelopes status callbacks (“StatusUpdateCallbackUrl”: “”,) are fired, based on envelope events/actions. There are also detailed callbacks available based on events. Consider, that our system expects the full callback url, including the parameter list you expect, with the placeholders that should be replaced by values at runtime. You can also add your own paramter for that envelope (e.g. internal references). Moreover, on our shared SaaS environments only HTTPS (port 443) callbacks are allowed. Placehoder for callback URL: - ##EnvelopeId##
- ##Action##
- workstepFinished : when the workstep was finished
- workstepRejected : when the workstep was rejected
- workstepDelegated : whe the workstep was delegated
- workstepOpened : when the workstep was opened
- sendSignNotification : when the sign notification was sent
- envelopeExpired : when the envelope was expired
- workstepDelegatedSenderActionRequired : when an action from the sender is required because of the delegation
Consider, that our system expects the full callback url, including the parameter list you expect, with the placeholders that should be replaced by values at runtime. You can also add your own paramter for that envelope (e.g. internal references). Moreover, on our shared SaaS environments only HTTPS (port 443) callbacks are allowed. Sample: https://www.mycallback.at?envelope=##EnvelopeId##&action=##Action## Sample with custom parameter “internalid“: https://www.mycallback.at?envelope=##EnvelopeId##&action=##Action##&internalid=1234
You can forward all eventtyps to your callback url or use a - blacklist: all events, except the events in the blacklist, are fired
- whitelist: only the events in the whitelist are fired
- empty blacklist/whitelist: all events are fired
Do not use blacklist and withlist at the same time! If you only want to use the event callbacks, use an empty envelope callback in the configuration (<callbackUrl /> ) The following placeholders are defined: - ##WorkstepId## – workstep of current action
- ##EventType## – type of event (see list of types below)
- ##Source## – internal (eSAW) or external (Viewer)
- ##Time## – time when the action occurred
- ##Description## – textual description of the event
- ##RecipientEmail## – emailadress of current recipient
- ##EnvelopeId## – current envelope id
- ##RecipientOrder## – index of current recipient
Definition without black-/whitelist:
Code Block |
---|
| <envelope>
...
<workstepEventCallback>
<url>http://www.mycallback.at?envelopeId=##EnvelopeId##&recipientEmail=##RecipientEmail##&recipientOrder=##RecipientOrder##</url>
</workstepEventCallback>
<steps>
...
</steps>
</envelope> |
Blacklist-Definition Code Block |
---|
| <workstepEventCallback>
<url>http://www.mycallback.at?envelopeId=##EnvelopeId##&recipientEmail=##RecipientEmail##&recipientOrder=##RecipientOrder##</url>
<blacklist>
<event>SomeEventName</event>
<event>SomeDifferentEventName</event>
</blacklist>
</workstepEventCallback> |
Whitelist-Definition Code Block |
---|
| <workstepEventCallback>
<url>http://www.mycallback.at?envelopeId=##EnvelopeId##&recipientEmail=##RecipientEmail##&recipientOrder=##RecipientOrder##</url>
<whitelist>
<event>SomeEventName</event>
<event>SomeDifferentEventName</event>
</whitelist>
</workstepEventCallback> |
These events are fired by the Workstep Controller (internal component) and are fired before the data in eSAW is complete updated (some postprocessing is required). Therefore this event callbacks are used only in rare integrations. Available Event TypesConfirmTransactionCode – A transaction code was sent DefaultEventType – Not specially defined event type AgreementAccepted – The user accepted the agreement AgreementRejected – The user rejected the agreement RequestPrepareAuthenticationInformationSuccess – The request for additional authentication infos was requested PrepareAuthenticationSuccess – The prepare authentication process succeeded AuthenticationFailed – The user failed to authenticate AuthenticationRejected – The user rejected the authentication process AuthenticationSuccess – The user succeeded to authenticate ReAuthenticationFailed – The reauthentication process failed AuditTrailRequested – The audittrail was requested AuditTrailXmlRequested – The audittrail XML was requested CalledPage – The viewer site was requested WhoIsInformation DocumentDownloaded – The document download was requested FlattenedDocumentDownloaded – The flattened document download was requested AddedAnnotation – An annotation was added AddedAttachment – An attachment was added AppendedDocument – A document was appended FormsFilled – A form field was filled ConfirmReading – A reading task was completed PageViewChanged – The user scrolled SendTransactionCode – This event is raised, when a TransactionCode for a signature with type TransactionCode* has been sent using the IdentityServer or the TransactionCodeSenderPlugin PrepareSignWorkstepDocument – A signature is prepared for signing SignWorkstepDocument – Try to sign a signature UndoAction – An action was undone WorkstepCreated – A workstep was created WorkstepFinished – A workstep was finished WorkstepRejected – A workstep was rejected DisablePolicyAndValidityChecks EnablePolicyAndValidityChecks AppendFileToWorkstep – A file was appended to the workstep AppendTasksToWorkstep – A task was added to the workstep SetOptionalDocumentState – A optional document became either active or inactive StartBatch – A batch signing process started EndBatch – A batch signing process ended PreparePayloadForBatch – The payload is getting prepared for batch signing Draft CallbacksDraft callbacks are fired, if a draft is used or deleted. The draft callback is set in the “CreateDraftOptions” (“AfterSendCallbackUrl”: “”), via the following call: https://demo.xyzmo.com/Api/v4.0/envelope/create Sample: https://www.mycallback.at?draft=##DraftId## ErrorIn general, our REST endpoint returns different HTTP status codes: - 200 OK
- 204 NoContent (response is empty (e.g. download files))
- 40x return an error code and error info
- 400 BadRequest (envelope description is incorrect)
- 401 Unauthorized (User is not authorized)
- 404 NotFound
- 415 UnsupportedMediaType
- or HTTP 500 for generic server errors
|