Docs · Business plan
Webhooks
By Amit Dobal, 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=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdHitDM-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 twov1=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
- Read the raw request body (before any JSON parsing).
- Compute
HMAC-SHA256(secret, t + "." + body)as hex. The secret starts withhdmwh_; use the whole string. - Compare with each
v1=value in constant time. Reject if none match. - Reject if
tis 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 "", 200Payload
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.
