Custom Webhooks

Send custom metrics from any source using webhooks

Overview

The Webhooks integration allows you to send custom metrics from any source - Zapier, Make (Integromat), n8n, custom scripts, or any tool that can make HTTP requests.

Use Cases

• Track custom business events
• Monitor cron jobs and scheduled tasks
• Integrate legacy systems
• Send metrics from internal tools
• Aggregate data from multiple sources
• Track metrics not available in standard integrations

Features

• Unlimited Flexibility: Track any metric you can imagine
• Simple API: Just POST JSON to your webhook URL
• Secure: API key authentication
• Real-time: Metrics appear instantly
• Batch Support: Send multiple metrics in one request

Setup Instructions

Step 1: Create Webhook Connection

1. Go to your project dashboard
2. Click on Integrations in the sidebar
3. Find Custom Webhooks in the Custom category
4. Click Connect
5. Give your webhook a name (e.g., “Cron Job Metrics”)
6. Click Create

Step 2: Copy Your Credentials

You’ll receive:

• Webhook URL: https://yourdomain.com/api/webhooks/custom
• API Key: A secure token for authentication
• Project ID: Your project identifier

Keep these secure - treat them like passwords!

Step 3: Send Your First Metric

curl -X POST https://yourdomain.com/api/webhooks/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "YOUR_PROJECT_ID",
    "metrics": [{
      "metricId": "daily_signups",
      "metricName": "Daily Signups",
      "value": 42,
      "unit": "count",
      "timestamp": 1234567890000
    }]
  }'

Step 4: View Your Metrics

• Metrics appear instantly in your dashboards
• Create widgets to visualize your custom metrics
• Set up alerts on custom metrics (Pro+)

API Reference

Endpoint

POST https://yourdomain.com/api/webhooks/custom

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body

{
  "projectId": "string (required)",
  "metrics": [
    {
      "metricId": "string (required, unique identifier)",
      "metricName": "string (required, display name)",
      "value": "number (required)",
      "unit": "string (optional, e.g., 'USD', 'count', '%')",
      "timestamp": "number (optional, Unix timestamp in ms, defaults to now)",
      "metadata": "object (optional, additional data)"
    }
  ]
}

Response

Success (200):

{
  "success": true,
  "metricsStored": 1
}

Error (400/401/500):

{
  "error": "Error message"
}

Integration Examples

Zapier

1. Create a new Zap
2. Choose your trigger (e.g., “New Row in Google Sheets”)
3. Add action: Webhooks by Zapier → POST
4. Configure:
   • URL: Your webhook URL
   • Payload Type: JSON
   • Headers: Authorization: Bearer YOUR_API_KEY
   • Data: Map your fields to the metrics format

Make (Integromat)

1. Create a new scenario
2. Add your trigger module
3. Add HTTP → Make a Request module
4. Configure:
   • URL: Your webhook URL
   • Method: POST
   • Headers: Add Authorization header
   • Body: JSON with metrics data

n8n

1. Create a new workflow
2. Add your trigger node
3. Add HTTP Request node
4. Configure:
   • Method: POST
   • URL: Your webhook URL
   • Authentication: Header Auth
   • Body: JSON with metrics

JavaScript/Node.js

const axios = require('axios');

async function sendMetric(metricId, metricName, value) {
  try {
    const response = await axios.post(
      'https://yourdomain.com/api/webhooks/custom',
      {
        projectId: 'YOUR_PROJECT_ID',
        metrics: [{
          metricId,
          metricName,
          value,
          unit: 'count',
          timestamp: Date.now()
        }]
      },
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('Metric sent:', response.data);
  } catch (error) {
    console.error('Error sending metric:', error.message);
  }
}

// Usage
sendMetric('daily_signups', 'Daily Signups', 42);

Python

import requests
import time

def send_metric(metric_id, metric_name, value):
    url = 'https://yourdomain.com/api/webhooks/custom'
    headers = {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
    data = {
        'projectId': 'YOUR_PROJECT_ID',
        'metrics': [{
            'metricId': metric_id,
            'metricName': metric_name,
            'value': value,
            'unit': 'count',
            'timestamp': int(time.time() * 1000)
        }]
    }

    response = requests.post(url, json=data, headers=headers)
    print(f'Metric sent: {response.json()}')

# Usage
send_metric('daily_signups', 'Daily Signups', 42)

Best Practices

Metric IDs

• Use consistent, descriptive IDs (e.g., daily_signups, api_response_time)
• Use snake_case for readability
• Don’t change IDs once created (historical data won’t match)

Metric Names

• Use human-readable names (e.g., “Daily Signups”, “API Response Time”)
• Keep names concise but descriptive
• Use title case for consistency

Units

• Always specify units when applicable (USD, ms, count, %)
• Be consistent with units across similar metrics
• Use standard abbreviations

Timestamps

• Send timestamps in Unix milliseconds
• If omitted, current time is used
• Don’t send future timestamps

Batching

• Send multiple metrics in one request when possible
• Reduces API calls and improves performance
• Maximum 100 metrics per request

Error Handling

• Always check response status
• Implement retry logic for failed requests
• Log errors for debugging

Troubleshooting

401 Unauthorized

• Verify your API key is correct
• Check that the Authorization header is properly formatted
• Ensure the API key hasn’t been revoked

400 Bad Request

• Verify your JSON is valid
• Check that all required fields are present
• Ensure value is a number, not a string

Metrics Not Appearing

• Check that projectId matches your project
• Verify metricId is consistent
• Wait a few seconds and refresh the dashboard

Rate Limiting

• Free tier: 100 requests per hour
• Pro tier: 1,000 requests per hour
• Scale+ tier: 10,000 requests per hour

Security

• Never expose your API key in client-side code
• Use environment variables for credentials
• Rotate API keys periodically
• Monitor webhook usage for suspicious activity
• You can revoke and regenerate API keys anytime

Support

Need help with webhooks?

• Email: [e-mail]
• Check our FAQ
• Join our Discord community