...
After you have setup the Webhook successfully, it can be triggered (called) from external. To do so, send a GET or POST HTTP request to the webhook url which was returned when you created it. For example:
| Code Block |
|---|
https://hub-try.pipeforce.org/api/v3/command/webhook.receive?token=abcdef |
| 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 |
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 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?correlationId=<ID> |
Whereas <ID> must be replaced by the pipeforce-result-correlationid from the header.
This endpoint will return a 302 MOVED status code with a Location header as long as the result is not ready. In this case, another request can be executed after a few seconds. If the HTTP client can follow redirects, it will be automatically redirected again to this endpoint after a few seconds. Otherwise, you need to call this endpoint manually after a few seconds.
If the result is ready and can be retrieved, a 200 OK status code is returned with the result in the body and redirects will stop.
Auto-redirect to result endpoint
...
Result JSON
Any successful webhook call will respond with a JSON in the response body.
Processing response
The default JSON in 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 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?pipeforce-result-correlationid=<ID> |
Whereas <ID> must be replaced by the pipeforce-result-correlationid from the header.
This endpoint will return a 302 MOVED status code with a Location header as long as the result is not ready. In this case, another request can be executed after a few seconds. If the HTTP client can follow redirects, it will be automatically redirected again to this endpoint after a few seconds. Otherwise, you need to call this endpoint manually after a few seconds.
If the result is ready and can be retrieved, a 200 OK status code is returned with the result in the body and redirects will stop.
Auto-redirect to result endpoint
When calling the webhook endpoint, it is by default always returning 200 OK and the final result value may or may not be in the response JSON (depending on whether the background process takes longer than the request process). 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. It will do as many redirects as required and return with the final result when finished. So there is no extra work on client side necessary.
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.
...
| Code Block | ||
|---|---|---|
| ||
pipeline:
- event.listen:
eventKey: webhook.lead.created
- iam.run.as: systemuser
- mail.send:
to: name@company.tld
subject: "New lead was created!"
body: ${@convert.fromBase64(body.payload.origin)}
|
...
| Code Block | ||
|---|---|---|
| ||
pipeline:
- event.listen:
eventKey: webhook.lead.created
- iam.run.as: systemuser
- mail.send:
to: name@company.tld
subject: "New lead was created!"
body: ${body.payload}
|
For security reasons, by default, the webhook pipeline is executed with very limited anonymousUser privileges. So, make sure that you use only commands in your pipeline which can be executed by this user. In case you need more privileges, you can use the iam.run.as command as shown in this example to switch to the privileges of the given user before executing the command. See the IAM portal for the permissions (or roles) of a given user. Also see Groups, Roles, and Permissions for more details on user privileges / permissions.
...