Webhooks

How it works

When your saved search finds new companies, NewcoHunter sends a POST request to your webhook URL with the company details as a JSON payload. You can use this to build custom integrations with any system that accepts HTTP requests - your own API, a cloud function, a database, or a third-party service.

What data syncs

Each JSON payload includes company name, Companies House number, incorporation date, registered address (line 1, city, region, postcode, country), SIC codes, and - where enrichment data exists - the company website URL, platform, and confidence level. Payloads also include the name of the saved search that triggered the event and a timestamp.

Who it is for

Webhooks are designed for developers and technical teams who want to build custom automations on top of NewcoHunter data. Common use cases include syncing leads into an in-house CRM, triggering enrichment pipelines, posting alerts to custom notification systems, and appending records to internal databases. The integration also works with automation platforms such as Make and n8n.

Frequently asked questions

What plan do I need?

Webhooks require a Pro plan or above. You can create multiple webhooks pointing to different endpoints, and optionally scope each one to a specific saved search.

What happens if my endpoint is unavailable?

NewcoHunter retries failed deliveries automatically. After 10 consecutive failures the webhook is disabled to prevent repeated errors, and you can re-enable it from the Webhooks page once your endpoint is healthy again.

Setup guide

1. Go to your Webhooks page
2. Click "Add Webhook"
3. Enter a name and your endpoint URL
4. Optionally add a signing secret for payload verification
5. Optionally link to a specific saved search, or leave blank for all searches
6. Click Create, then use "Test" to verify delivery

Payload format

Each delivery is a POST request with Content-Type: application/json:

{
  "event": "new_matches",
  "search_name": "Tech companies in London",
  "match_count": 5,
  "companies": [
    {
      "company_number": "15123456",
      "company_name": "ACME SOLUTIONS LTD",
      "company_status": "active",
      "company_type": "ltd",
      "incorporation_date": "2026-04-10",
      "address": {
        "line_1": "10 Downing Street",
        "locality": "London",
        "region": "Greater London",
        "postal_code": "SW1A 2AA",
        "country": "United Kingdom"
      },
      "sic_codes": ["62012", "62020"],
      "website_url": "https://acme-solutions.co.uk",
      "website_platform": "wordpress",
      "website_confidence": "verified"
    }
  ],
  "fired_at": "2026-04-12T09:00:00.000Z"
}

Verifying signatures

If you set a signing secret, every request includes an X-NewcoHunter-Signature header. This is an HMAC-SHA256 hex digest of the raw request body, using your secret as the key.

To verify in Node.js:

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Reliability and retry behaviour

• Each delivery has a 10-second timeout
• A response with HTTP status 2xx is considered successful
• Any other status (or timeout/network error) counts as a failure
• After 10 consecutive failures, the webhook is automatically disabled
• A successful delivery resets the failure counter to zero
• You can re-enable a disabled webhook from the Webhooks page

Headers

Use cases

• Custom CRM sync - push leads into an internal CRM or database
• Cloud functions - trigger an AWS Lambda or Google Cloud Function for custom processing
• Data enrichment pipelines - feed new companies into your enrichment workflow
• Alerting - send notifications via custom channels (Teams, Discord, etc.)