...
| Note |
|---|
In order to secure the token in your url, you should always prefer a HTTPS connection between the two systems (which is by default always the case in PIPEFORCE), and send the |
Result JSON
Any webhook will respond with a JSON in the response body.
Processing response
The default response body of a webhook request is of this format:
| Code Block | ||
|---|---|---|
| ||
{
"statusCode": 200,
"status": "processing",
"value": null,
"pollingRedirectEnabled": false,
"correlationId": "467609e2-cd8a-48ef-922a-8b107b523b35",
...
} |
If you just want to send a message to the server and you’re not interested in any response, you can ignore this JSON in the response body. Otherwise, it contains information about the task and how to retrieve the result.
As you can see, in this example status is set to "processing" since the webhook has triggered a task in the background which is still processing ( = task running longer than the request process). Therefore, no result value is set: "value": null.
Additionally, pollingRedirectEnabled is set to false, which is the default. So no auto-redirect to the polling endpoint is done. See below for more details on this.
The correlationId can be used to do polling for the final result, once the background task has been finished. Also see below for more details on this.
OK response
In case the webhook was calling a very short-running task which could finish during the non-blocking request time, it is returned with the response. In this case, the result JSON in the body will look similar to this:
| Code Block | ||
|---|---|---|
| ||
{
"statusCode": 200,
"status": "ok",
"value": "HELLO WORLD",
"pollingRedirectEnabled": false,
"correlationId": "617609e2-cd3a-50ef-921a-3b107b523b30",
...
} |
| Info |
|---|
Note: Since a webhook call is non-blocking, it will not wait for the result value. In case processing the result value takes longer than the request process, the final result must be fetched in an additional step using polling and the
|
Polling for result
Calling a webhook is by default executed async. This means a webhook call like this will start the execution of the webhook but will not wait for a response of it. Instead, it will return immediately with a 200 OK status code but without any result.
In case you expect a result, you can retrieve it using long polling: The webook call returns the header pipeforce-result-correlationid. You can use this id in from the header in order to poll for the result of the webhook at the /api/v3/result endpoint:
| Code Block |
|---|
https://main-try.pipeforce.net/api/v3/result?correlationIdpipeforce-result-correlationid=<ID> |
Whereas <ID> must be replaced by the pipeforce-result-correlationid from the header.
...
When calling the webhook endpoint, it is by default always returning 200 OK without any result in the body. If the caller client supports redirects, you can set the parameter pollingRedirectEnabled to true on the webhook call. :
| Code Block |
|---|
https://hub-try.pipeforce.org/api/v3/command/webhook.receive?token=abcdef&pollingRedirectEnabled=true |
In this case the webhook endpoint will return a redirect to the /api/v3/result endpoint and will use the polling approach as described above.
You can also set the request parameter pollingRedirectEnabledon the /api/v3/result endpoint to stop or start the auto-redirect for polling at any time:
| Code Block |
|---|
https://hubmain-try.pipeforce.orgnet/api/v3/command/webhook.receive?token=abcdefresult?pipeforce-result-correlationid=<ID>&pollingRedirectEnabled=truefalse |
Polling maximum and wait time
...
In case the polling result doesn't exists or was cleaned-up in the cache already, a status code 410 GONE is returned.
...