Callbacks

Callbacks are triggers which can be subscribed to, so as to notify an integrating system when certain events occur.

Unlike the API calls which are HTTP Posts, callbacks are HTTP Get requests to a predefined URL. When a callback event occurs, the deployment will send a request to each URL that subscribes to it, meaning different systems can integrate to the same events. There are currently 3 callback events are available.

OrderCreated

OrderCreated occurs when a user places an order but before it may be approved or generated.

CallbackURL?name="0"&id="OrderID"&site="SiteCallbackID"

The CallbackURL must be a fully formed URL to the service listening for the callback.
For this callback, the name will be 0 to correspond with its enumeration.
Because this callback event is for an order, the the id will always be an OrderID.
The SiteCallbackID is the value defined in the configuration.

OrderReadyForProduction

OrderReadyForProduction occurs when all items in an order have been approved and artwork is ready to be generated.

CallbackURL?name="1"&id="OrderID"&site="SiteCallbackID"

The CallbackURL must be a fully formed URL to the service listening for the callback.
For this callback, the name will be 1 to correspond with its enumeration.
Because this callback event is for an order, the the id will always be an OrderID.
The SiteCallbackID is the value defined in the configuration.

OrderItemRendered

OrderItemRendered occurs once artwork has been generated for an order item.

CallbackURL?name="2"&id="OrderItemID"&site="SiteCallbackID"

The CallbackURL must be a fully formed URL to the service listening for the callback.
For this callback, the name will be 2 to correspond with its enumeration.
Because this callback event is for an order item, the the id will always be an Order Item ID.
The SiteCallbackID is the value defined in the configuration.

Configuration & Testing

Once the integration is enabled, an new “ROI Web API” page will appear in the administration menu, where callbacks can be configured and tested.

On this page is is possible to add a new callbacks. Each callback must have an event type selected and a valid URL. The URL is tested before it is saved to the system.

Existing callbacks can be modified or deleted once added.

The button at the bottom of the page sends a test to every registered callback. Testing is performed by accessing the callback URL with the ‘test=test’ parameter (e.g. http://www.testurl.com?test=test or https://www.testurl.com?api-key=XZ123&test=test). The expected response value from the callback URL is the string ‘test’.

CallbackURL?test="test"

In addition to the callback configuration page, callbacks can be managed using the API calls listed below.

RegisterCallback

This call registers a new callback to the provided endpoint.

Request

POST /roiwebinterface.asmx HTTP/1.1
Host: host
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <RegisterCallback xmlns="http://roidistribution.com/webapi">
      <eventId>OrderCreated or OrderReadyForProduction or OrderItemRendered</eventId>
      <url>string</url>
      <token>string</token>
    </RegisterCallback>
  </soap12:Body>
</soap12:Envelope>

<eventId> - the value of the Event type to subscribe to
<url> - the fully qualified URL for the callback
<token> - the authorisation token to validate the API call

Response

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <RegisterCallbackResponse xmlns="http://roidistribution.com/webapi" />
  </soap12:Body>
</soap12:Envelope>

The call returns an error if it fails to create a new reference to a callback.

UnregisterCallback

This call deletes an existing callback. Request

POST /roiwebinterface.asmx HTTP/1.1
Host: host
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <UnregisterCallback xmlns="http://roidistribution.com/webapi">
      <eventId>OrderCreated or OrderReadyForProduction or OrderItemRendered</eventId>
      <url>string</url>
      <token>string</token>
    </UnregisterCallback>
  </soap12:Body>
</soap12:Envelope>

<eventId> - the value of the Event type to unsubscribe from
<url> - the fully qualified URL for the callback
<token> - the authorisation token to validate the API call

Response

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <UnregisterCallbackResponse xmlns="http://roidistribution.com/webapi" />
  </soap12:Body>
</soap12:Envelope>

The call returns an error if it fails to remove the requested callback reference.