Callback

Generate a URL that can be called by another system to send status updates (sometimes called a webhook) or to redirect a user to an action in an external system (for example an iDeal payment). You can download this system service from Grexx Marketplace.

This is a composite system service that consists of the following:

• System service - Callback: The underlying system service that is not designed to be called directly.
• System service - Generate callback URL: A wrapper around the callback system service. We recommend using this system service to generate callback URLs.
• Callback response handler: A callback response handler casetype for processing calls to the callback. Using this system service is optional. As an alternative, you can create a form activity to process responses.

Process overview

The process for generating and using a callback is as follows:

1. You use a casetype activity to create a system service case with the correct attribute values. We recommend creating a Callback response handler case. If you already know what needs to happen when a response is received, you can also provide the response type, response body, response headers, response code and/or response redirect URL.
2. The system service returns a unique callback URL in one of two forms, where $state is always in the form of a UUID:
   • If State query parameter is empty (default): https://example.grexx.today/cb/2bc7679c-f514-47a1-a4fc-89d6a0e13529 according to the formula $boxUrl/cb/$state
   • If State query parameter is populated: https://example.grexx.today/cbq/state/?state=33931129-8459-4714-8c9b-ad9d15090289 according to the formula $boxUrl/cbq/$stateQueryParameter?$stateQueryParameter=$state
3. You pass the generated URL to the other system via a consumer web service (or another method such as a redirect).
4. The other system does one of the following:
   • If your callback is of type response, then the other system will call your URL, probably with some data you can use.
   • If your callback is of type redirect, then the user will be sent back to this URL.
5. Your callback activity from step 1 is now called. You have the option to determine what should be done now by filling (or overriding) the response type, response body, response headers, response code and/or response redirect URL attributes.
6. The callback does what you asked for based on the Response type:
   • With redirect we redirect the user to the Response redirect url.
   • With response we give a response using the Response code, Response body, and Response headers.

Input

The following inputs apply to both the Callback and Generate callback URL system services. We recommend using a casetype activity to create a Generate callback URL case, which in turn will create a Callback case with the same values.

Attribute	Data type	Mandatory?	Description
Callback activity	Case ID	Yes	The activity to invoke when the callback is invoked. This can either be a casetype activity that creates a Callback response handler case, or a form activity.
Callback activity case	Case ID	No	If the above activity is on a case other than the current case, specify the case ID here.
State query parameter	String	No	Defaults to empty. If empty, the callback URL is in the format $boxUrl/cb/$state (e.g. https://example.grexx.today/cb/2bc7679c-f514-47a1-a4fc-89d6a0e13529) If you enter a state, the callback URL is in the format $boxUrl/cbq/$stateQueryParameter?$stateQueryParameter=$state (e.g https://example.grexx.today/cbq/state/?state=33931129-8459-4714-8c9b-ad9d15090289). This is useful if you need to connect to standardized systems or methods such as SAML or oAuth, where you have to provide a URL in advance and you can only send them a state while making a callback.
Retryable after error?	Boolean	No	If true, this case and its callback URL will remain available when incorrect data is sent. This means if the request fails, you can try again. If false, you are not allowed to try again.
Allow multiple calls?	Boolean	No	Determines whether the callback can be called more than once. If false, the callback system service closes the moment the callback is called (if Retryable after error is true only after a successful call, if Retryable after error is false always after 1 call). If true, The callback system service remains open and Retryable after error has no added value. To make the callback unavailable, you must close the system service case itself.
Alternative domain	String	No	Can be filled with a different domain starting with https:// to customize the callback URL.
Response input fields			Use these fields to enter the data that will be used when the callback is called by the external system or user.
Response type	String	Yes	Enter redirect to redirect the user to a URL. Enter response to give an external system a response.
Response redirect URL	String	No	Required if type is redirect. The URL to which the user should be redirected. For cases and pages on your own platform, use /case/caseId (e.g. /case/1:142:432) or /page/thankyou. For redirects to other boxes or applications, use the full URL, e.g. https\://www\.nu.nl or https\://my.grexx.today/case/1:5412:231
Response body	String	No	For type response. The body of the response. The format depends on the external system but can be in any form such as XML, JSON, CSV, or plain text.
Response code	Integer	No	For type response. The return code. Default: 200. For more information, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
Response headers	JSON	No	For type response. The response headers. This can be useful if you want to provide the content type for an external system. For example: { "content-type": "application/json", "x-custom-field":" custom-value" }

Output

The Callback system service itself has no output because the case is only closed if Allow multiple calls is false and a callback is requested. The case is never closed automatically if Allow multiple calls is true.

If you invoke the Callback system service using the Generate callback URL system service, the following output is provided when the Generate callback URL case is closed.

Attribute	Data type	Mandatory	Description
Callback URL	String	No	The callback url.
Callback state	String	No	Release the state in case you have to send it separately to the external system, for example with a SAML connection.
Callback caseid	Case ID	No	The Case ID of the system service case. This is useful if you want to close the system service to make the callback unavailable.

If you want to use the Callback system service purely without the Generate callback URL wrapper, you can use the "Created case metadata" from the On Submit stage of the activity to store the case ID and then extract this data from the casedata of the system service.

The callback response handler casetype

The Callback response handler casetype is imported when you import the Callback system service from Grexx Marketplace. You can use this casetype to process calls to the callback. Alternatively you can create your own casetype. When creating your own casetype, ensure the attributes have the external references listed below. This means that instead of a casetype activity, you can also use a form activity with fields with the same external references.

You can create mappings to populate the input fields listed below with values from the Callback case. During the On Start stage of the activity, you can adjust the Response values to determine what should happen when the callback is invoked.

Attribute	Data Type	External reference	Description
Request body	String	requestBody	The request body with which the external party invoked the callback.
Request headers	JSON	requestHeaders	The request headers with which the external party invoked the callback.
Request method	String	requestMethod	The request method (get, post, put, delete, patch) with which the external party invoked the callback.
Request query	JSON	requestQuery	The query string in JSON format. /cb/11111111/?id=5&status=ok&from=afas becomes {"id":"5", "status": "ok", "from": "afas"}
Callback system service case	Case ID	callbackSystemCase	Case ID of the system service callback.
Response type	String	responseType	See Input above. Here you will get the value that you may have mapped there. You are free to adjust this via the casedata.
Response body	String	responseBody	See Input above. Here you will get the value that you may have mapped there. You are free to adjust this via the casedata.
Response code	Integer	responseCode	See Input above. Here you will get the value that you may have mapped there. You are free to adjust this via the casedata.
Response headers	JSON	responseHeaders	See Input above. Here you will get the value that you may have mapped there. You are free to adjust this via the casedata.
Response redirect url	String	responseRedirectUrl	See Input above. Here you will get the value that you may have mapped there. You are free to adjust this via the casedata.