Webhooks & Events

Overview

Webhooks allow you to receive real-time HTTP notifications when specific events occur within your DataPulse workspace. When an event is triggered, DataPulse sends an HTTP POST request to your configured endpoint URL with a JSON payload containing the event details.

How Webhooks Work

The webhook delivery flow follows this pattern:

1. An event occurs in your DataPulse workspace (e.g., a dataset is updated)
2. DataPulse packages the event into a JSON payload
3. The payload is POSTed to your registered endpoint URL
4. Your server responds with a 2xx status code to acknowledge receipt
5. If delivery fails, DataPulse retries with exponential backoff (1s, 5s, 30s, 2m, 10m)

Quickstart: Setting Up a Webhook

curl -X POST https://api.datapulse.io/v2/webhooks \
  -H "Authorization: Bearer dp_live_sk_4f8a2b..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/datapulse",
    "events": [
      "dataset.created",
      "dataset.updated",
      "analytics.report.completed"
    ],
    "secret": "whsec_your_signing_secret"
  }'

import hmac
import hashlib
import json

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(
        f"sha256=" + expected,
        signature
    )

# Usage in your handler
body = request.get_data()
sig = request.headers.get("X-Datapulse-Signature")
if not verify_webhook(body, sig, WEBHOOK_SECRET):
    return "Invalid signature", 401

const express = require('express');
const app = express();

app.post('/webhooks/datapulse', express.json(), (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'dataset.created':
      console.log(`New dataset: ${event.data.name}`);
      break;
    case 'analytics.report.completed':
      notifyTeam(event.data);
      break;
    default:
      console.log(`Unhandled event: ${event.type}`);
  }

  res.status(200).send();
});

Webhook Request Format

When DataPulse sends a webhook, the request includes specific headers and a JSON body. Here is what to expect:

Request Headers

Request Body Schema

{
  "id": "evt_2xK9mL4pR7nQ",
  "type": "dataset.created",
  "created_at": "2025-11-15T14:32:01Z",
  "workspace_id": "ws_8fA2bC3d",
  "data": {
    "id": "ds_9kL3mN4p",
    "name": "Q4 Marketing Performance",
    "rows": 145280,
    "columns": 24,
    "created_by": "user_7hG6jK"
  }
}

Event Types

DataPulse supports 24 event types across four categories. Subscribe to the events relevant to your integration needs.

Analytics Events

Dataset Events

Integration Events

System & Security Events

Complete Event Reference

A comprehensive list of all supported webhook event types and their descriptions.

Webhook Management API

Manage webhook endpoints programmatically using the following API endpoints.

Create a Webhook

List Webhooks

curl https://api.datapulse.io/v2/webhooks \
  -H "Authorization: Bearer dp_live_sk_4f8a2b..."

Delete a Webhook

Signature Verification

Every webhook request is signed using HMAC-SHA256. You must verify the signature before processing any event to prevent unauthorized requests.

Signature Algorithm

Verification Examples

import hmac
import hashlib
import time

def verify_signature(payload, signature, secret, tolerance=300):
    """Verify webhook signature with timestamp tolerance."""
    # Parse signature: "sha256=abc123,t=1699900000"
    sig_parts = signature.split(",")
    sig_hash = None
    timestamp = None
    
    for part in sig_parts:
        if part.startswith("sha256="):
            sig_hash = part
        elif part.startswith("t="):
            timestamp = int(part.split("=")[1])

    # Check timestamp tolerance (5 minutes)
    if timestamp and abs(time.time() - timestamp) > tolerance:
        raise ValueError("Webhook timestamp expired")

    expected = hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(
        f"sha256=" + expected,
        sig_hash
    )

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const [sigHash, timestamp] = signature.split(',');
  const ts = parseInt(timestamp.split('=')[1]);

  // Check timestamp tolerance
  if (Date.now() / 1000 - ts > 300) {
    throw new Error('Webhook timestamp expired');
  }

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return sigHash === `sha256=${expected}`;
}

Retry Policy

When your endpoint fails to respond with a 2xx status code, DataPulse automatically retries the delivery using an exponential backoff strategy.

Best Practices

• Always verify signatures — Never process webhook payloads without validating the X-Datapulse-Signature header.
• Respond quickly — Acknowledge receipt with a 200 response within 5 seconds, then process asynchronously.
• Handle duplicates — Track processed event IDs to prevent double-processing from retries.
• Use HTTPS only — Webhook endpoints must use HTTPS. HTTP endpoints are rejected.
• Set timeout handling — If processing takes longer than 5 seconds, return 200 immediately and process in a background queue.
• Monitor failed deliveries — Set up a separate webhook for webhook.delivery.failed to get notified when deliveries permanently fail.
• Use environment secrets — Store webhook signing secrets in environment variables or a secrets manager, never in source code.

Troubleshooting

Common Issues

Debugging Tips

1. Use the DataPulse Dashboard's webhook event log to inspect recent delivery attempts, status codes, and response times.
2. Test your endpoint with tools like webhook.site or ReqBin during development.
3. Check your server's TLS configuration — DataPulse requires TLS 1.2 or higher.
4. Verify your endpoint is publicly accessible (not behind a firewall or private network without a tunnel).

Frequently Asked Questions