How to Write Webhook URLs

Anne Rosebery
Platform Admins
2.x

Webhooks connect space actions, such as submission submitted, with a workflow (or an action in another system). To take the desired action when the webhook fires, the correct endpoint/URL must be entered in the webhook. Generally, the best way to do this is to leverage attributes and variables.

Note: example provided here connect the Request and Task platform components for submission submitted.

Suggested Space Attributes:

  • Task Server Scheme: http or https. The scheme used by the task server
  • Task Server Host: the hostname for the task server
  • Task Source Name: the name for the source to be used within the Task component of the platform

These attributes are necessary to construct the first part of the URL without hard coding anything:

${space('attribute:Task Server Scheme')}://${space('attribute:Task Server Host')}/kinetic-task/app/api/v1/run-tree/${space('attribute:Task Source Name')}

It is necessary to separately define the task server scheme and host because of the way attributes are encoded when included in a URL. If the :// were included in the attribute, they would be encoded, and that is not desired in this case.

What follows this part of the URL is specific to the action taken. See this article to determine how to figure out which group goes with which action. For this example, we will use a submission submitted. Note that the URL will work for any kapp and slug because variables are used in the webhook definition.

${space('attribute:Task Server Scheme')}://${space('attribute:Task Server Host')}/kinetic-task/app/api/v1/run-tree/${space('attribute:Task Source Name')}/Submissions%20%3E%20${kapp('slug')}%20%3E%20${form('slug')}/Submitted