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
webso_events_retries	Number of retries. -1 (default) means infinitive retries	3

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>.

<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.

<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:

STATUS_CHANGE

fired when the status of a signature request changes, the following data is sent:

document_id: The document ID

from: The old status

to: The new status

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:

{
   "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

document_id: The document ID

fields_signed: The amount of signed fields (of this user)

The event data is sent per HTTP POST as a JSON object:

{
   "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

field_status: The field status : "signed" or "rejected"

document_id: The document ID

user_id: The user ID

The event data is sent per HTTP POST as a JSON object:

{
   "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:

{
   "event":"RENDER_RETURN",
   "status":"success",
   "document_id":"1234"
}

Integration

The JSON object can be processed like this (Java):

@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 after the time defined in webso_events_retry. If webso_events_retry isn't set, the call won't be repeated.

Browser not supported