Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gethuntd.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Webhooks allow you to receive notifications when company lookup jobs complete.

​
Setting Up

Webhooks can be configured in two ways:

​
Option 1: Per-Request Configuration

Include webhook_url when submitting a company lookup: 
{
  "domain": "example.com",
  "webhook_url": "https://yourapp.com/webhooks/huntd"
}

​
Option 2: Dashboard Configuration

You can configure a default webhook URL in the Huntd Dashboard. Once configured in the dashboard, the webhook URL is associated with your API key—you don’t need to include it in every API call.
Dashboard-configured webhooks eliminate the need to send webhook_url with every request. All lookups made with that API key will automatically use the configured webhook.
Webhook URLs must use HTTPS.

​
Webhook Payload

When a job completes, we send a POST request to your webhook URL with the following payload: 
{
  "job_id": "job_1705596234567_a1b2c3d4",
  "domain": "example.com",
  "source": "source_name",
  "status": "success",
  "contacts": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "job_title": "Senior Software Engineer",
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "company": "Example Corp",
      "company_domain": "example.com",
      "verifications": [
        {
          "source": "source_name",
          "isVerified": true,
          "verifiedAt": "2024-01-18T12:25:00.000Z",
          "status": "verified"
        }
      ]
    }
  ],
  "credits_used": 1,
  "created_at": "2024-01-18T12:30:00.000Z"
}

​
Webhook Headers

HeaderDescription
X-Huntd-SignatureHMAC-SHA256 signature
X-Huntd-TimestampUnix timestamp

​
Verifying Signatures

const crypto = require('crypto');

function verifySignature(payload, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

​
Retry Policy

If your endpoint returns a non-2xx status, we retry:
AttemptDelay
1Immediate
21 minute
35 minutes
430 minutes
52 hours

​
Best Practices

  • Respond with 200 immediately
  • Process data asynchronously
  • Always verify signatures
  • Use the job_id to deduplicate