In general communication with the RIPS API has to be initiated by the client. There are some cases where this architecture is not desirable. For example, the client does not know when a scan finishes, so it has to ask the API regularly about the state of the scan until it is finished. As a solution callbacks were introduced in RIPS API 2.8. A callback is a HTTP URL that is called by the API on certain events, for example when a scan is finished.


Callbacks are JSON-encoded HTTP POST requests. A callback consists of 3 sections:


Action is a string that specifies the cause of the callback.


Item is an associative array that represents the state of the object that caused the callback to happen.


Class is a string that specifies the class name of the object in item.


For security reasons a callback URL has to fulfill the following criteria, otherwise it is ignored.

  • http
  • https
  • 80
  • 443
  • 6000-9000 (RIPS API < 2.16)
  • 1025-65535 (RIPS API >= 2.16)

Everything but:

  • localhost

Everything but:

  • /latest/meta-data
  • /latest/user-data
RedirectsDoes not follow redirects

This first layer of protection is not sufficient to completely prevent Server-Side Request Forgery. Thus, the SaaS version of RIPS sends all requests through the proxy server (


Callbacks can be bound to users, applications, and scans. Callbacks for applications automatically apply to all scans of that application as well. It is necessary to specify the events that trigger the callback through the parameter "reports". Possible values are "UPDATE_USER", "DELETE_USER", "CREATE_SCAN", "UPDATE_SCAN", "FINISH_SCAN", "CREATE_COMMENT", "CREATE_REVIEW", and "DELETE_COMMENT". More information about the input and output can be found in the API specification.

Example Scan Callback
   "action" : "FINISH_SCAN",
   "item" : {
      "percent" : 100,
      "id" : 14,
      "upload_removed" : false,
      "phase" : 0,
      "application" : {
         "id" : 1
      "version" : "callback-test",
      "start" : "2018-01-26T15:59:39+00:00",
      "tags" : [],
      "analysis_depth" : 5,
      "loc" : 12604,
      "created_by" : {
         "id" : 1
      "php" : {
         "id" : 14,
         "allow_url_fopen" : true,
         "register_globals" : false,
         "allow_url_include" : false,
         "major_version" : "5",
         "filter_default" : "unsafe_raw",
         "magic_quotes_gpc" : false,
         "minor_version" : "3",
         "release_version" : "29"
      "code_stored" : true
   "class" : "Application\\Scan"


When designing a callback system make sure to consider that the callbacks are visible to all users of your organization with the role "chief".


You can use to easily test the callback feature.