> ## 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.

# Webhooks

> Receive notifications for async operations

## 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:

```json theme={null}
{
  "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](https://app.gethuntd.com). 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.

<Tip>
  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.
</Tip>

<Note>
  Webhook URLs must use HTTPS.
</Note>

## Webhook Payload

When a job completes, we send a POST request to your webhook URL with the following payload:

```json theme={null}
{
  "job_id": "job_1705596234567_a1b2c3d4",
  "domain": "example.com",
  "source": "source_name",
  "status": "success",
  "contacts": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "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

| Header              | Description           |
| ------------------- | --------------------- |
| `X-Huntd-Signature` | HMAC-SHA256 signature |
| `X-Huntd-Timestamp` | Unix timestamp        |

## Verifying Signatures

```javascript theme={null}
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