...
...
...
...
...
Configuration
WebSignatureOffice can be configured to call an URL on certain events. This functionality is activated by setting the URL to be called in the config.ini:
webso_events_url=https://host/servlet (example URL)
...
| key | description | example |
|---|---|---|
| webso_events_url | The url which is called. | https://host/servlet |
| webso_events_filter |
...
| A comma seperated list of events that should be fired |
...
| . If this option is not set, all events are fired |
...
| RENDER_RETURN,USER_FINISH | |
| webso_events_retry |
...
| The time waited in |
...
| milliseconds until the event call is repeated. If this option is not set, the event won't be fired again. |
...
| 3000 |
additional Request Header
It is possible to add additional request header with the config webso_events_keys and the corresponding webso_events_values.
webso_events_keys is a comma seperated list with header names. webso_events_values is a comma seperated list, which contains the values for the corresponding key.
| key | description | example |
|---|---|---|
| webso_events_keys | The keys as comma seperated list. | example 1: webso_events_keys=user,password example 2: webso_events_keys=Authorization |
| webso_events_values | The values as comma seperated list. | example 1: webso_events_values=foo,bar example 2: webso_events_values=Basic Zm9vOmJhcg== |
The request contains the header user=foo and password=bar. In the second example a basic auth header is used.
TyrService XML upload
There is also a way to set a callback URL for each document via XML upload (processXML parameter).
If the uploaded XML contains a single document, the <CallbackUrl> is defined under <ESign>.
| Code Block |
|---|
<ESign> <CallbackUrl>https://websignatureoffice.stepover.de: |
...
8445/demoServlet></CallbackUrl>
...
<PDF>...</PDF>
</ESign> |
If the uploaded XML contains an envelope, the <CallbackUrl>s are defined for each document individually.
| Code Block |
|---|
<ESign> <SignatureRequestEnvelope> <Documents> <Document> <CallbackUrl>https://websignatureoffice.stepover.de:8445/demoServlet |
...
/bar></CallbackUrl> |
...
<PDF>...</PDF> ... </Document> <Document> <CallbackUrl>https://websignatureoffice.stepover.de:8445/demoServlet/foo></CallbackUrl> <PDF>...</PDF> |
...
... </Document> </Documents> ... </ESign> |
If no <CallbackUrl> is defined, the URL from the server config is used.
Events
These following events are supported:
...
fired when the status of a signature request changes, the following data is sent:
document_id: The document ID
...
status: 1 = new, 2 = partially signed, 3 = finished, all signed, 4 = failed, not all signed
The event data is sent per HTTP POST as a JSON object:
| Code Block |
|---|
{ "from":"1", "to":"2", "event":"STATUS_CHANGE", "document_id":"23822" } |
- USER_FINISH
fired when a user finished all of his signatures of a signature request, the following data is sent:
user_id: The user ID
...
The event data is sent per HTTP POST as a JSON object:
| Code Block |
|---|
{ "user_id":"1", "event":"USER_FINISH", "document_id":"27268", "fields_signed":"2" } |
- FIELD_SIGNED_OR_REJECTED
fired when a signature field was signed or rejected, the following data is sent:
field_id: The signature field ID
...
The event data is sent per HTTP POST as a JSON object:
| Code Block |
|---|
{ "field_id":"12", "field_status":"signed", "event":"FIELD_SIGNED_OR_REJECTED", "document_id":"27268", "user_id":"1" } |
- RENDER_RETURN
fired when the document rendering has finished, the following data is sent:
status: error or success
document_id: The document ID
Please note: The event RENDER_RETURN can't be send to the url defined in an TyrService upload. The server setting URL is used instead.
The event data is sent per HTTP POST as a JSON object:
| Code Block |
|---|
{ "event":"RENDER_RETURN", "status":"success", "document_id":"1234" } |
...
Integration
The JSON object can be processed like this (Java):
| Code Block |
|---|
@Override
protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
String jsonString = IOUtils.toString(req.getInputStream());
try
{
JSONObject json = new JSONObject(jsonString);
String statusFrom = json.getString("from");
String statusTo = json.getString("to");
String event = json.getString("event");
String documentId = json.getString("document_id");
//do something
}
catch (JSONException e)
{
e.printStackTrace();
}
resp.setContentType( "text/html" );
resp.setStatus(200);
return;
} |
The receiving service must return a return code 200 on success. If no 200 is received the call is repeated in 5 seconds (default value, can be changed by setting after the time defined in webso_events_retry. If webso_events_retry).
...
isn't set, the call won't be repeated.