TABLE OF CONTENTS


Intro - What are Webhooks anyway?

Webhooks are the most common, modern way of apps to interact with each other and tell each other that something has changed. So it is kind of a ping, "hey, please do something something changed on my end". E.g. a user profile has updated in your own backend application and you want another SaaS application, like e.g. Salesforce, to change the user details of that particular user in their app. In this case, you would create a webhook in the  app (Salesforce) and include it in your own backend application in a way that whenever a user is updated in your own system, it also pings Salesforce that an update occurred. A webhook can however not only notify about a particular resource, but also pass on information in the form of JSON in its so-called body. 


How do webhooks work?


A webhook can be created for each flow if you drag & drop the webhook icon at the beginning of the flow to the workspace. If you now either click on the status button or the Edit button, you see the webhook URL to trigger the particular webhook which looks like this e.g. 

https://api.dynamicinsight.com/v1/flow-webhook/*some id* where *some id* is replaced with your flow's id. How you can get the URL easily is described below?



The easiest way to get the webhook URL and the Bearer token is by clicking on the edit button in the 

Flow Builder.


1. Click `Edit`

How to get to the Webhook endpoint and security Bearer token of a flow


2. Get the Webhook-Endpoint for your specific flow and the secret Bearer token to secure it

Webhook endpoint and security Bearer token



Flow statuses of flows using webhooks


Webhooks work on the flow status `draft` or `live`, but they don't work on status `paused`. Use status `paused` if you want to disable webhook usage from someone triggering it externally.



Webhook security Bearer token


For additional security, are enabled by default with a secret Bearer token that needs to be passed in the header in the form of:

Authorization: Bearer ey...


Here Authorization is the header name, Bearer is the header type, which needs to be followed by an empty space, and than flowed by the secret token ey... which usually is a >50 characters long and in this example only abbreviated with ey... .


Using Webhook request body data


If you send a request body in your POST request to a webhook, you can use the data in your flow. E.g. let's assume you send the following request body in your webhook's body as part of the POST request and the webhook has the ref-id `web1`:

{
   "company_id": 123456
   "user_id": 789123
}

You can access those variable with a combination of the ref-id and the keys of the request body e.g. 


{{ web1.company_id }} will yield 123456


This allows you to pass any data you wish to dynamic insight.


Webhook responses body

You can determine two webhook responses, the http status code and the actual response value:


Webhook response body example

You can include responses in your webhooks id Jinja2. A common response would look like this:

{ "valid":

{% if res1.value == "myResult"  %} 
   "{{ res1.value}}"
{{ else }} 
   false
{% endif %}

}

This returns res.value if the request is true and otherwise valid: false in a JSON.


Webhook http status code

The response status code should be one of the three digit http status code numbers.