TrailSpark

Connecting Clay

Overview

Clay connects as a two-sided round trip: TrailSpark pushes each account's correlation_id and website domain into a webhook source in your own Clay table, you design the enrichment inside Clay, and an HTTP API column in your Clay table sends the results back to TrailSpark through a callback URL you set up there. Because both sides have to be wired up, connecting Clay is a two-step handshake rather than a single paste-and-go.

This also means Clay credits are spent by the columns you run in your Clay table — not by TrailSpark. TrailSpark's own caps (see Enrichment Rules & Budget Caps) control how many accounts get sent to Clay; what each one costs in Clay credits depends on the columns you've built.

Before you start (in Clay)

In Clay, create a webhook source in the table you want TrailSpark to push accounts into, and copy that webhook's URL. You'll paste it in the next step.

Step 1: Paste your Clay webhook URL

Go to Settings > Integrations, find Clay in the Data enrichment section, and click Configure.

  • Connection name — a label for this connection (e.g., "Clay production")
  • Clay webhook URL — paste the URL you copied from the webhook source you created in Clay. It's stored securely and never shown again.
  • Auth header (optional) — only fill this in if your Clay webhook requires a header to accept requests. Leave both Auth header name and Auth header value blank otherwise.

Click Connect.

Step 2: Copy your one-time setup values

Right after you connect, TrailSpark shows a one-time screen: "Copy these now — they're shown only once." It has two values:

  • Callback URL — where Clay sends company details back to TrailSpark
  • Ingest token — proves the callback request really came from your Clay table

Copy both immediately. For your security, TrailSpark can't show the ingest token again — if you lose it, disconnect Clay and reconnect to get a new one and a new callback URL.

Step 3: Finish setup in Clay

The same screen walks through a "Finish setup in Clay" checklist:

  1. Webhook source added. Done automatically — you already pasted its URL in Step 1.
  2. Map the incoming correlation_id field to a column in your Clay table. TrailSpark uses it to match Clay's answer back to the right account.
  3. Send a sample row so Clay knows your columns. Clay only shows the correlation_id and domain columns after your table receives its first row — click Send sample row, then refresh the Clay table to see them. TrailSpark uses one of your real account domains for the sample when it can, so the preview looks like a real row; the row itself is throwaway (its correlation_id is setup-sample) and safe to delete once you're done.
  4. Add an "HTTP API" enrichment column in Clay that sends a POST request to your Callback URL, with the header x-trailspark-ingest-token set to your Ingest token. In the request body, include correlation_id plus the company details you want to return: industry, employee_count, region, and market_segment.
  5. Turn on auto-run for the table so new accounts are enriched automatically as they arrive.

When you're done, click "I've saved these — finish setup."

Two kinds of columns, two jobs

A working Clay table for TrailSpark typically has two kinds of enrichment columns, and it's worth keeping their jobs separate:

  • A data column, like Clay's Enrich Company — this is Clay's own waterfall: it looks up industry, employee count, location, funding, and more from the domain column. This is the column that spends your Clay credits, per row per column.
  • An HTTP API column — this doesn't look anything up. It just delivers the values you choose (from your data column, or typed directly) back to TrailSpark. Pick the "HTTP API (headers)" integration when you add it.

A minimal working table has one waterfall column feeding one HTTP API column.

Setting up the HTTP API column

A few specifics that are easy to miss:

  • Set the method to POST first — the body editor only appears once the method is set to POST.
  • The endpoint is your Callback URL, and the header value comes from your Ingest token — both from the one-time setup screen in Step 2. The token is shown once; if you lose it, disconnect and reconnect to get a new one.
  • Add the header on the column configuration itself. If your Clay workspace has a saved "header account" at the connection level, don't rely on it here — headers saved that way may not be applied to the request, which shows up as a 401 from TrailSpark even though the token is correct. Set x-trailspark-ingest-token directly on the column.

The request body: keys are typed, values are picked

The JSON keys in the body — correlation_id, domain, industry, employee_count, region, market_segment — are typed in literally. These are the names TrailSpark recognizes; don't rename them. The values next to each key are / references you pick from your table's columns: the webhook columns for correlation_id and domain, and your waterfall column's outputs for the rest.

If your waterfall doesn't have an exact region or market_segment output, map the closest one it does have (HQ country for region, for example), or add a small formula column in Clay that derives it. You can also just leave a key out entirely — TrailSpark never writes an empty value, and an empty value never overwrites a field you already have filled in.

Clay's HTTP API column should POST a JSON body shaped like this:

json
1{
2  "correlation_id": "abc123",
3  "domain": "acme.com",
4  "industry": "Software",
5  "employee_count": 120,
6  "region": "North America",
7  "market_segment": "Mid-Market"
8}

A few things to know about the contract:

  • correlation_id (or correlationId) is required — it's how TrailSpark matches the answer back to the right account.
  • Field names can be either style — employee_count or employeeCount, market_segment or marketSegment — TrailSpark reads both.
  • Extra fields are welcome. Anything else your waterfall returns — funding stage, tech stack, whatever you find useful — can be added as its own key. After your first results come back, each one appears as a custom field under Enriched fields on the Enrichment rules tab, where you turn on the ones you want to use in ICP rules, scoring context, and destinations. See Enrichment Rules & Budget Caps.
  • If Clay couldn't find a match for an account, send "matched": false (or "status": "no_match") instead of the company-detail fields, so TrailSpark records it as no match rather than guessing.

After you're connected

Once connected, the page shows "Clay is connected." Your webhook URL is saved securely and never shown again — to replace it, disconnect and reconnect.

  • Test connection checks that your setup is complete (a valid webhook URL and an issued ingest token). It never sends a real row to Clay, so it never uses up your webhook's lifetime submissions.
  • Disconnect stops TrailSpark from pushing any more accounts to this webhook. To swap in a different webhook URL or auth header, disconnect and reconnect.

Nearing your webhook's lifetime limit

Clay webhook sources accept only a fixed number of submissions over their lifetime. As you approach that limit, TrailSpark shows a warning: "This Clay webhook is nearing its lifetime limit." When you see it, create a new webhook source in Clay, then disconnect and reconnect here with the new URL — that resets the limit and keeps company details flowing without interruption.

Next Steps