Signup webhooks

This is not the same as Lookup Webhooks, which deliver Company Lookup job results (company_lookup.completed). The two are unrelated — make sure you are wiring up the one you want.

Registering an endpoint

Go to Settings → API & webhooks in the Huntd Dashboard.

Add your URL

It must be a public https:// URL. Redirects are not followed.

Copy your signing secret

You receive a signing secret (whsec_…). Unlike an API key it stays readable, because you need it to verify our signature. It grants no access to Huntd.

Send a test

Use the Send test button to fire a synthetic event, so you can confirm your receiver works before any real traffic arrives.

The request we send

POST /their/endpoint HTTP/1.1
Content-Type: application/json
X-Huntd-Event: signup
X-Huntd-Delivery: 1041
X-Huntd-Timestamp: 1785400000
X-Huntd-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015…

{
  "event": "signup",
  "id": "e117b1d2-5a34-4943-8a1d-6201be9437a0",
  "occurredAt": "2026-07-31T20:00:05.460Z",
  "organization": "acme.com",
  "data": {
    "source": "devin",
    "email": "mike.burton@globex.com",
    "firstName": "Mike",
    "lastName": "Burton",
    "jobTitle": "Director, IT Architecture",
    "company": "Globex",
    "companyDomain": "globex.com",
    "industry": "financial services,insurance",
    "location": "Columbus, OH, United States",
    "linkedinUrl": "https://linkedin.com/in/example",
    "verifiedAt": "2026-07-31T19:01:57.707Z",
    "previouslyNotUserAt": "2026-07-23T20:02:28.302Z"
  }
}

Fields

string

Event type. Only signup exists today.

string

Unique event ID. Key on this for idempotency — see delivery.

string

UTC timestamp of when we detected the signup.

string

Your organization’s domain.

string

When we confirmed this person is a user.

string

When we last confirmed they were not a user. The signup happened between these two timestamps.

Verifying the signature

Compute HMAC-SHA256 over `${timestamp}.${rawBody}` using your signing secret, and compare it to X-Huntd-Signature.

Use the raw request body, before JSON parsing. Re-serializing a parsed object changes the bytes and the signature will not match.

The timestamp is part of the signed material, so a captured payload cannot be replayed with a fresh header. Reject anything older than about 5 minutes.

import crypto from 'node:crypto';

function verify(req, rawBody, secret) {
  const ts = req.headers['x-huntd-timestamp'];
  const sig = String(req.headers['x-huntd-signature'] || '').replace(/^sha256=/, '');
  const expected = crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(sig, 'hex');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}

Delivery behaviour

Acknowledge with any 2xx. The timeout is 10 seconds — respond fast and do your work asynchronously.
Retries: 5 attempts with backoff — 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours — after which the delivery is marked failed.
Redirects are not followed.
No replay on registration. A newly registered endpoint starts from “now”. To backfill, use /people?discovered_days=N.

At-least-once delivery

Each event is queued at most once per endpoint, so retrying a failed delivery does not create duplicates. But if we time out after your server already processed the event, the retry is a genuine duplicate.

Key on id and make your handler idempotent. This is the single most common source of double-processing.

Unknown event types

Only event: "signup" exists today, but the payload is event-typed via both the event field and the X-Huntd-Event header. Ignore event types you do not recognize rather than erroring, so new event types do not break your receiver.

Two caveats worth reading

Timing — this is not real-time

The event fires when Huntd detects the signup, not the moment it happens. We re-verify accounts daily and check for changes hourly, so an event typically arrives within a few hours.That is timely enough for a Slack alert and saves you polling entirely — but do not build anything that assumes sub-minute delivery.

Getting started

Public API

Company Lookup

Overview

Signup webhooks

Registering an endpoint

The request we send

Fields

Verifying the signature

Delivery behaviour

At-least-once delivery

Unknown event types

Two caveats worth reading

​Registering an endpoint

​The request we send

​Fields

​Verifying the signature

​Delivery behaviour

​At-least-once delivery

​Unknown event types

​Two caveats worth reading

Registering an endpoint

The request we send

Fields

Verifying the signature

Delivery behaviour

At-least-once delivery

Unknown event types

Two caveats worth reading