Connecting a KPI to a custom Webhook

If you would like to automatically update your KPIs in Topicflow, but the source of truth is not yet supported with a native integration, you can use our custom webhook feature.

A webhook is a URL to which you can send data that will update the value of your KPI. One option is for a developer to write software that will periodically send updates to this URL. Another option is to use the webhook URL with integration tools like Zapier

You can find the webhook URL for your KPI by going to the specific KPI page in Topicflow and clicking the "Webhook" button at the top. This will display an example of the request needed to update the KPI, and there is a button to click to copy the URL. Be sure to keep this URL private, as anyone who knows it may use it to update the value of your KPI.

If you are writing your own software to send data, you must send a POST request to this URL. The body of the request may contain either JSON or form-encoded data.

Within this data, you must specify either a "measurement" value or an "increment" value. In both cases, the value assigned to this variable should be a number. If you specify "measurement", a new KPI measurement will be created in Topicflow with the value you specify. If you specify "increment", a new KPI measurement will be created in Toipcflow that is equal to the most recent measurement that already exists (or 0 if there is none) plus the value you send

The purpose of the increment value is if you do not keep track of the current value of the KPI in your system, but you know when it changes and by how much. An example of this could be the number of users using a service. Your software might not know the total, but might run each time a new user signs up. In this case, you could send an "increment" value of "1" to the webhook URL, which would increase the value of the KPI in Topicflow by 1.

You may also specify a "timestamp" value in the body of your request. If not specified, the new measurement that is created will be timestamped with the current time. But if you are using the webhook to, for example, backfill historical data, you may wish to specify times in the past for your measurements. If specified, the value should be an ISO 8601 formatted timestamp.