e) Callback-API

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) 

Further configuration options are:

webso_events_filter:  a comma separated list of events that should be fired, if this option is not set, all events are fired.

webso_events_retry: the time waited in milli seconds untill the event call is repeated.

There is also a way to set a callback URL for each document via XML upload (processXML parameter):

<ESign>
<CallbackUrl>https://websignatureoffice.stepover.de:8445/demoServlet></CallbackUrl>
...
<PDF>...</PDF>
</ESign>

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

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

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

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 in 5 seconds (default value, can be changed by setting webso_events_retry).