Webhook Triggers

webhooks are a type of event stream that enables products, vendors, or services to push real time communication in turbine they process and enrich data to send from third party services and platforms to turbine records starting in turbine 26 2 0 , you can choose how the incoming webhook request body is parsed on configure > outputs instead of relying only on content type auto detection use this when a vendor sends json without a json content type, form encoded data without the expected header, or raw text such as xml or syslog you will handle in playbook logic click save or save and close after making changes view existing webhooks to view existing webhooks navigate to orchestration click webhooks from here you can toggle the enabled button to enable or disable the webhook, or click the desired webhook to view settings and log information create webhook triggers to create a webhook trigger, create a new playbook, upload a playbook, or search for an existing playbook on the playbook, click add a trigger click catch webhook on trigger, enter a webhook title and click generate url or the webhook will not be created once the generate url button has been clicked, the webhook's url is generated in the webhook url field and the copy url link is enabled next, you can edit the webhook settings edit webhook settings to change webhook settings on trigger, click edit webhook on the settings tab, you can update the webhook title, add properties to authenticate the webhook requests, copy the url, and enable/disable the webhook on the logs tab, you can view the webhook logs, view by date, and enable/disable the webhook click save and close to save updates if you do not need to edit your webhook, you can go straight to configuring configure webhooks review create and edit playbook inputs https //app archbee com/docs/wdlpsa7glls1ghfgxbo9d/ lgnydbj4charvn4 9vko before configuring webhooks for best practices you are ready to start the configuration process for your webhook click configure to get started the webhook configuration window has three tabs webhook events, outputs, and map to playbook inputs webhook events tab this tab shows the event type with a drop down arrow, which shows you the webhook details, the result, and discovered outputs navigate to discovered outputs and testing https //app archbee com/docs/wdlpsa7glls1ghfgxbo9d/0m vna2te15i4mshcdnj1 for details on how to view and/or add discovered outputs, the agent/host for that webhook, the time the webhook was last received, and the numbered of triggered playbooks related to that webhook outputs tab this tab shows you all the outputs from the webhook these are default property types if you added any discovered outputs, then they show up with the delete hyperlink any property types without that delete hyperlink are part of the original returned inputs from the webhook under additional options , select a payload format option to control how turbine parses the incoming webhook request body into $event data body the radio options are auto detect , body as json , body as raw text , and url encoded params this setting controls parsing only; it does not change what the sending system posts or the content type header on the request option when to use auto detect default turbine uses the request content type header form url encoded bodies are parsed as key/value pairs; other types use json parsing (same behavior as before 26 2 0) body as json always parse the body as json, regardless of content type use when a vendor sends json without a json content type body as json supports json only; use body as raw text for xml, rss, or other non json text body as raw text store the body as a string without parsing use for xml, syslog text, or other formats you will handle in playbook logic url encoded params always parse the body as application/x www form urlencoded key/value pairs, regardless of content type use when a vendor sends form encoded data without the expected header payload format options are on the configure dialog outputs tab ( additional options ), not on edit webhook > settings click apply on the configuration dialog to save a changed format to the webhook sensor send a new test payload after apply to verify parsing unlike the http request test tab, unsaved format changes do not affect incoming webhooks map to playbook inputs tab remember the important note on reviewing create and edit playbook inputs https //app archbee com/docs/wdlpsa7glls1ghfgxbo9d/ lgnydbj4charvn4 9vko for best practices? that is because on this tab, if you do not see any inputs, it is because your playbook currently does not have any inputs you can add them, and they will display on this tab and just like the action inputs, you can click add a property to see the drop down menu you can add a playbook property or expression selecting playbook property opens the property drawer where you can select the desired property to map filter tab the filter tab allows you to apply a condition on event triggers allowing you to prevent the playbook execution unless the criteria is met you can select a condition type from the drop down next to matches $event data properties here is the list of top level properties that are defined on the $event data object url (object) the url components of the request href (string) the full url of the request protocol (string) the protocol used for the request hostname (string) the hostname of the request port (integer) the port of the request pathname (string) the pathname of the request query (object) the query parameters of the request as key/value pairs hash (string) the hash of the request headers (object) the headers of the request as key/value pairs body (null|array|boolean|number|object|string) the request body after parsing type and shape depend on the payload format option on the outputs tab authenticate webhooks to configure webhook authentication settings on trigger , click edit webhook on the settings tab, click add a property , then click authentication the authorization property displays with a sub property option basic authentication select basic authentication basic authentication specifies the credentials to be sent in and verified from the authorization header using the basic authentication scheme complete the username and password fields, and click save mirror the username and password with your third party system to remove basic authentication, click the vertical ellipsis, then click remove shared secret authentication select shared secret authentication shared secret authentication specifies the credentials to be sent in and verified from one of the following locations in the webhook requests header, body, or query parameter complete the secret , secret format , and secret location fields to complete the secret location , click add a property from the drop down menu, select one of the following properties request body – extract the secret (password) from the request body request header – extract the secret (password) from the request header request query parameter – extract the secret (password) from a query parameter to remove these properties, click the vertical ellipsis, then click remove troubleshooting payload format symptom what to check body is a string but you expected an object on configure > outputs > additional options , select body as json if the vendor sends json without a json content type body is parsed incorrectly as json select body as raw text for non json payloads, or url encoded params for form posts without the expected header webhook request fails before the playbook runs with body as json , the body must be valid json use auto detect or body as raw text if the sender posts non json content format change does not apply click apply on the configure dialog after changing the option send a new test payload to the webhook url — existing events on webhook events were parsed with the previous saved format view webhook logs on trigger , click edit webhook and then click the logs tab you can view the logs enable or disable the webhook filter by date using jump to date