HitDM

Docs · Business plan

Webhooks

By , founder of HitDMUpdated

HitDM sends a signed HTTPS POST to your endpoint when something happens in your account: a lead comes in, a link is clicked. Add endpoints in Integrations.

  • 6delivery attempts, with backoff
  • 5 minsignature replay window
  • 8 sto answer with any 2xx

The request

POST /hooks/hitdm HTTP/1.1
Content-Type: application/json
User-Agent: HitDM-Webhooks/1.0 (+https://hitdm.com/docs/webhooks)
HitDM-Webhook-Id: evt_3f0c…
HitDM-Webhook-Timestamp: 1763114400
HitDM-Signature: t=1763114400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
  • HitDM-Webhook-Id: the event id. Retries and re-sends reuse it, so store it and ignore repeats.
  • HitDM-Signature: t= unix seconds, then one or two v1= values. Two appear for 24 hours after you rotate the secret (new and old).
  • Answer with any 2xx within 8 seconds. Redirects are not followed and count as a failure.

Verify the signature

  1. Read the raw request body (before any JSON parsing).
  2. Compute HMAC-SHA256(secret, t + "." + body) as hex. The secret starts with hdmwh_; use the whole string.
  3. Compare with each v1= value in constant time. Reject if none match.
  4. Reject if t is more than 5 minutes from your clock (replay protection).

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.HITDM_WEBHOOK_SECRET; // hdmwh_...

// Keep the RAW body: the signature covers the exact bytes we sent.
app.post("/hooks/hitdm", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("HitDM-Signature") ?? "";
  const parts = Object.groupBy(header.split(","), (p) => p.split("=")[0]);
  const t = Number(parts.t?.[0]?.slice(2));
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(400); // replay

  const expected = crypto.createHmac("sha256", SECRET).update(`${t}.${req.body}`).digest("hex");
  const ok = (parts.v1 ?? []).some((p) => {
    const got = Buffer.from(p.slice(3), "hex");
    return got.length === 32 && crypto.timingSafeEqual(got, Buffer.from(expected, "hex"));
  });
  if (!ok) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  // Dedupe on event.id (also sent as HitDM-Webhook-Id): retries reuse it.
  if (event.type === "lead.captured") saveLead(event.data);
  res.sendStatus(200); // answer fast (under 8 s); do slow work later
});

Python (Flask)

import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["HITDM_WEBHOOK_SECRET"].encode()

@app.post("/hooks/hitdm")
def hitdm():
    header = request.headers.get("HitDM-Signature", "")
    items = [p.split("=", 1) for p in header.split(",") if "=" in p]
    t = next((v for k, v in items if k == "t"), "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        abort(400)  # replay
    body = request.get_data()  # raw bytes
    expected = hmac.new(SECRET, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    if not any(hmac.compare_digest(v, expected) for k, v in items if k == "v1"):
        abort(400)
    event = request.get_json()
    # Dedupe on event["id"]; retries reuse it.
    return "", 200

Payload

Every event has the same envelope. version changes only for a breaking change; new fields can appear at any time, so ignore fields you do not know. Test events from the dashboard carry "test": true and sample data.

lead.captured

Someone sent their email or phone number in a DM.

{
  "id": "evt_3f0c…",
  "type": "lead.captured",
  "version": 1,
  "created_at": "2026-11-14T10:00:00.000Z",
  "account_id": "usr_…",
  "data": {
    "lead_id": "lead_sample",
    "email": "jo@example.com",
    "phone": null,
    "instagram_account_id": "17841400000000000",
    "contact_id": "1234567890",
    "contact_username": "jo.example",
    "automation_id": "auto_sample",
    "automation_name": "Free guide",
    "source": "comment",
    "workspace_id": "ws_sample",
    "is_new": true,
    "captured_at": "2026-11-14T10:00:00.000Z"
  }
}

link.clicked

Someone opened a tracked link from your DM (first click per person per 10 minutes).

{
  "id": "evt_3f0c…",
  "type": "link.clicked",
  "version": 1,
  "created_at": "2026-11-14T10:00:00.000Z",
  "account_id": "usr_…",
  "data": {
    "link_id": "link_sample",
    "slug": "abc123",
    "destination_url": "https://example.com/guide",
    "workspace_id": "ws_sample",
    "click_count": 42,
    "clicked_at": "2026-11-14T10:00:00.000Z"
  }
}

dm.sent (coming soon)

An automation sent a DM.

follow.gained (coming soon)

Someone followed you to unlock a link.

automation.triggered (coming soon)

A comment, story reply or DM matched an automation.

lead.captured fires again when the same person sends a second value (for example a phone number after an email); is_new is then false and lead_id is the same.

Retries, limits and safety

  • Up to 6 attempts. Waits between them: 30 s, 2 min, 10 min, 1 h, 4 h (with a little jitter).
  • After 20 failed attempts in a row, or a 410 Gone, the endpoint is turned off and you get an email. Turn it back on from Integrations.
  • The delivery log keeps the last 100 deliveries (7 days) with the status code and, for failures, the first 1 KB of your response.
  • Business includes 5 endpoints and 50,000 deliveries a month. At the limit, deliveries pause until the 1st (UTC); your automations keep running.
  • Endpoints must use HTTPS on port 443 and a public address. Private, loopback and cloud metadata addresses are refused.

Send your first event

Add an endpoint in Integrations and send a test event from the dashboard.Verify the signature, then go live.