Loops and webhooks

A Loop is a webhook destination with a fixed object type. You create it once in the dashboard. Then every task attached to it gets POSTed to your URL when it settles. No polling.

Create a Loop

Go to Loops in the dashboard and create one. You choose:

Name. Anything that tells you what the Loop is for, like “Inbound signups”.
Object type. company or person. This decides what a record sent to the Loop gets enriched as.
Webhook URL. Must be https and publicly reachable. Loopback and private addresses are rejected.

On creation you get a signing secret, shown once. Store it. You need it to verify every webhook we send. If you lose it, delete the Loop and create a new one.

Direct request or Loop?

The two paths run the same enrichment and return the same task. They differ in who decides what gets enriched and where the result goes.

	Direct request	Loop
Endpoint	`POST /v1/companies/enrich` or `POST /v1/people/enrich`	`POST /v1/loops/{id}/run`
Object type comes from	The endpoint	The Loop
Result delivery	You poll the task	We `POST` it to your webhook. You can still poll.
Cost	Same	Same

Use a direct request when the caller is waiting for the answer. Use a Loop when the result should land somewhere on its own, like a CRM record or a queue.

Send records to a Loop

curl -X POST "https://api.enrichloops.com/v1/loops/13d3c366-db0f-45c1-870d-7493e7d99c37/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"stripe.com"}'

The body is the same input the matching direct endpoint takes. A company Loop accepts domain or linkedinUrl. A person Loop accepts linkedinUrl or email, plus the optional tie-break hints from reverse email lookup. You get the same task response as a direct request, with the same 200 or 202 semantics. Once the task settles, we also deliver it to the Loop’s webhook. A disabled Loop rejects new records with 409. Tasks already in flight still complete and deliver.

Attach a direct request to a Loop

You can also keep calling the direct endpoints and add loop_id to the body:

curl -X POST "https://api.enrichloops.com/v1/companies/enrich" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"stripe.com","loop_id":"13d3c366-db0f-45c1-870d-7493e7d99c37"}'

The endpoint decides the object type. The Loop only receives the result. Use a Loop whose object type matches the endpoint, so your receiver gets the payload shape it expects.

The webhook we send

POST https://yourapp.com/webhooks/enrichment
Content-Type: application/json
User-Agent: EnrichLoops-Webhook/1
X-EnrichLoops-Event: task.succeeded
X-EnrichLoops-Delivery-Id: 9f1c2a3e-...
X-EnrichLoops-Signature: t=1754570000,v1=6c3a9f...

{
  "event": "task.succeeded",
  "task": {
    "id": "...",
    "object_type": "company",
    "status": "succeeded",
    "target": "stripe.com"
  },
  "data": { "name": "Stripe", "domain": "stripe.com", "...": "..." },
  "error": null
}

event is one of:

task.succeeded. data carries the company or person.
task.failed. error carries the same code and fields you would see when polling. For a person Loop, an ambiguous email lookup arrives this way.
test. Sent when you press Send test event in the dashboard.

X-EnrichLoops-Delivery-Id stays the same across retries of one delivery. Use it to deduplicate. Respond with any 2xx to acknowledge. Anything else counts as a failure and we retry.

Verify the signature

Every webhook is signed with your Loop’s secret, using the same scheme as Stripe:

X-EnrichLoops-Signature: t=<unix timestamp>,v1=<hex-encoded HMAC-SHA256>

The signature covers {timestamp}.{raw request body}. Verify it like this:

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(
  secret,
  rawBody,
  signatureHeader,
  toleranceSeconds = 300,
) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => {
      const i = p.indexOf("=");
      return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
    }),
  );

  const timestamp = Number(parts.t);
  if (
    !Number.isFinite(timestamp) ||
    Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds
  ) {
    return false; // missing, malformed, or too old: reject
  }

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

import hmac, hashlib, time

def verify_webhook(secret: str, raw_body: bytes, signature_header: str, tolerance_seconds: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(",") if "=" in p)
    timestamp = parts.get("t")
    if timestamp is None or abs(time.time() - int(timestamp)) > tolerance_seconds:
        return False

    signed_payload = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Verify against the raw request body, before any JSON parsing. Re-serializing the parsed body and comparing will not match.

Retries

If your endpoint does not respond with a 2xx, we retry on this schedule:

Attempt	Delay
1	immediately
2	10 seconds
3	1 minute
4	5 minutes
5	30 minutes
6	2 hours
7	6 hours

After the seventh attempt the delivery is marked failed. Delivery history and a manual retry button are in the dashboard under the Loop.

Manage Loops

Rename, disable, or delete a Loop from the dashboard. Disabling stops new records from being accepted. Tasks already in flight still complete and deliver.

Get started

Enrichment

Webhook delivery

Create a Loop

Direct request or Loop?

Send records to a Loop

Attach a direct request to a Loop

The webhook we send

Verify the signature

Retries

Manage Loops

​Create a Loop

​Direct request or Loop?

​Send records to a Loop

​Attach a direct request to a Loop

​The webhook we send

​Verify the signature

​Retries

​Manage Loops

Create a Loop

Direct request or Loop?

Send records to a Loop

Attach a direct request to a Loop

The webhook we send

Verify the signature

Retries

Manage Loops