Push Custom Data to Your Dashboard via Webhooks (No Code Required)

When API Polling Isn't Enough

TotalKPI's API polling feature works great for pulling data from external services on a schedule. But some data doesn't live behind a standard API:

• Internal metrics from your own application
• Build and deploy counts from CI/CD pipelines
• Custom calculations from scripts or cron jobs
• Event data from services that support webhooks but not pull-based APIs
• Metrics from spreadsheets that you update periodically

For these cases, TotalKPI supports inbound webhooks: you POST JSON data to a unique endpoint, and it appears on your charts automatically.

How the Inbound Webhook System Works

The flow is straightforward:

1. You create an API key in TotalKPI's settings
2. TotalKPI gives you a unique webhook URL
3. You send a POST request to that URL with your data as JSON
4. TotalKPI matches the payload against your JSON templates to extract the metric value
5. The extracted value is appended to the associated data source as a new data point

The key concept is JSON templates. These are mappings that tell TotalKPI which field in your JSON payload contains the metric value. You define the template once, and every subsequent payload that matches the same structure is processed automatically.

Step 1: Create an API Key

In your TotalKPI dashboard, go to Settings and create a new inbound API key. Give it a descriptive name like "GitHub Actions" or "Daily Revenue Script."

TotalKPI generates a unique key and shows you the webhook URL:

POST https://totalkpi.com/api/inbound/your-unique-key

Step 2: Send a Test Payload

Send your first payload using curl or any HTTP client:

curl -X POST https://totalkpi.com/api/inbound/your-unique-key \
  -H "Content-Type: application/json" \
  -d '{"metric": "deploy_count", "value": 12, "timestamp": "2026-03-15T10:00:00Z"}'

The first time you send a payload with a new structure, it appears as an "unmapped" payload in your settings. This is expected. TotalKPI needs you to tell it how to interpret the data.

Step 3: Map the Payload to a Data Source

In the settings UI, you'll see your unmapped payload. Click on it to create a JSON template:

1. Select which JSON field contains the value (e.g., value)
2. Optionally select which field contains the timestamp (e.g., timestamp). If omitted, TotalKPI uses the current time.
3. Assign the template to an existing data source or create a new one

Once mapped, all future payloads with the same structure are processed automatically. No manual intervention needed.

Common Integration Patterns

GitHub Actions: Track Deploy Count

Add a step to your GitHub Actions workflow that fires after a successful deployment:

- name: Report deploy to TotalKPI
  run: |
    curl -X POST https://totalkpi.com/api/inbound/your-key \
      -H "Content-Type: application/json" \
      -d '{"metric": "deploys", "value": 1}'

Each deploy sends a data point. Over time, you'll see deploy frequency on your chart and can overlay it with revenue, churn, or other metrics.

Zapier or Make: Connect Any Service

Use Zapier's webhook action to send data from any trigger to TotalKPI. For example:

• New Shopify order sends order value to TotalKPI
• New Intercom conversation sends support ticket count
• New Typeform response sends NPS score
• New Stripe payment sends payment amount

Set up the Zap with a webhook POST action pointing to your TotalKPI endpoint. Map the relevant fields to a simple JSON structure.

Cron Job: Daily Metric Snapshot

Write a simple script that runs daily and pushes a metric:

#!/bin/bash
# Get today's active user count from your database
ACTIVE_USERS=$(psql -t -c "SELECT count(*) FROM users WHERE last_seen > now() - interval '24 hours'")

curl -X POST https://totalkpi.com/api/inbound/your-key \
  -H "Content-Type: application/json" \
  -d "{\"metric\": \"daily_active_users\", \"value\": $ACTIVE_USERS}"

n8n Workflows: Self-Hosted Automation

If you use n8n for automation, add an HTTP Request node at the end of any workflow to push the result to TotalKPI. Works with any data source n8n can connect to.

Overlaying Webhook Data with Other Sources

The real power of webhooks is that the data they push lives alongside all your other data sources. A deploy count pushed from GitHub Actions sits on the same chart as your Stripe MRR pulled via API polling.

Create a combined view with your webhook data and any other source. The auto-normalization handles the scale differences automatically. Now you can see whether deploy frequency actually correlates with revenue, whether support tickets spike after deploys, or whether your custom internal metric predicts churn.

Tips for Reliable Webhooks

• Send data consistently. Whether hourly, daily, or per-event, keep a regular cadence so your time-series data is smooth.
• Include timestamps. If your events aren't real-time, include the timestamp in the payload so the data point lands on the correct date.
• Use descriptive metric names. Your JSON template maps by structure, so keep the payload schema consistent across sends.
• Monitor for failures. If a webhook fails (network issue, key expired), the data point is simply missed. Set up monitoring on your sending side to catch failures.

Get Started

Start a free trial and create your first inbound API key. Push a test payload and see it appear on your chart in real time. Then overlay it with your other metrics to find the correlations you've been missing.