Callback ServiceΒΆ

Many endpoints in Authentise’s services take a callback parameter. These callback parameters always include a URL and a method. Let’s take for example the following:

{
    ...,
    "callback"      : {
        "method"    : "POST",
        "url"       : "https://my.domain.net/some/resource/",
    }
}

This specifies that callback requests should be sent as a POST https://my.domain.net/some/resource/. When the method is POST or PUT callbacks will always be Content-Type: application/json and sent with a body that includes the callback data.

For the sake of our example let’s assume that the system needs to inform you that a model resource’s status has changed from processing to complete. The resource that has been updated is at https://print.authentise.com/test/abc-123/. Given the above callback configuration a request would be sent like:

PUT https://my.domain.net/some/resource/
Content-Type: application/json

{
    "status"    : "complete",
    "uri"       : "https://print.authentise.com/test/abc/",
}

If the callback method was specified as GET the same data would have been sent but it would have been done differently. For a GET standards require that we do not send a payload. Instead the information will be sent as URL-encoded query parameters. This same callback information would be sent as:

GET https://my.domain.net/some/resource/?status=complete&uri=https%3A%2F%2Fprint.authentise.com%2Ftest%2Fabc%2F

There is no body and therefore no Content-Type header. All of the data is encoded in the request URL.

In both cases the system will retry the request every 30 seconds for 24 hours until it receives a 200-level response code indicating it was successful.

Callbacks will always include the URI of the resource that has changed and all properties that have changed. If the property that has changed is nested then dot separators will be used.