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"
}
| Header | Description |
|---|
X-Huntd-Signature | HMAC-SHA256 signature |
X-Huntd-Timestamp | Unix 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:
| Attempt | Delay |
|---|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
Best Practices
- Respond with 200 immediately
- Process data asynchronously
- Always verify signatures
- Use the job_id to deduplicate
