Skip to main content

Clay

You can use Evinor with Clay without an app or a listing, in two ways that need nothing from Clay: a sensor pushes matching events into a Clay table, or a Clay column pulls events for each company in a list you already have. This page is a recipe for both. It is not a native Clay integration.

What the integration offers​

PathHow it worksBest forCost
PushA sensor's Webhook destination posts each matching event to a Clay table's webhook source. Each delivery becomes a row.Watching a set of entities and getting only the events that match.The sensor is charged per match.
PullHTTP API columns in Clay call Evinor once per row: first to find the entity by its domain, then to search its events.Backfilling a company list you already have.Each event search is charged. See Cost.

Start with push. It delivers only matches, so a quiet entity costs nothing. Pull runs one charged search per row, and most rows of a typical list have no events.

Push: sensor to Clay table​

  1. In Clay, open a workbook and choose + Add, then Webhooks, then Monitor webhook. Copy the webhook URL. Each JSON POST to it updates the table.
  2. In the Evinor web app, open the sensor's Delivery step, add a Webhook destination and paste the Clay URL. See Receiving webhooks.
  3. To see a row before a real event arrives, send a test delivery. Call POST /v1/sensors/{id}/test-deliveries with a separate key that has SENSORS_WRITE, never the Clay key, and the Clay URL as url in the JSON body. Or use the test button in the sensor editor. A test delivery sends one synthesized sample event, so the row it creates in Clay is fake data. It consumes no credits, and you can send at most 5 per account every 10 minutes.
  4. Map fields from the delivery into columns:
FieldWhat it holds
payload.details.generatedSentenceA one-line summary of the event.
payload.details.roles[]The extracted roles, a list (a code may repeat). Each entry has code, textValue, and where present parsedAmount, parsedAmountUnit, parsedDate and namedEntityId.
payload.externalEventIdThe underlying event id. Use it to deduplicate. See Deduplicating.

namedEntityId is the canonical entity id. It is what you pass as involved_entity_ids when you pull events for the same company.

Signatures and the verified path​

Clay cannot verify X-Evinor-Signature, so a sensor pointed straight at Clay delivers unverified rows: anyone who learns the URL can add rows that look like Evinor events. A sensor destination carries only a URL, so a direct push also cannot send Clay's optional x-clay-webhook-auth token or its x-clay-webhook-idempotency-key header.

The n8n node and the Zapier app (not a Catch Hook) verify deliveries, but neither forwards to Clay with the signature intact. If you need verified rows, point the sensor at your own receiver instead of at Clay. The receiver:

  1. rejects unsigned or invalid deliveries (see Signature verification);
  2. rejects stale timestamps and any idempotencyKey it has already processed (see Replay protection);
  3. keeps the Clay URL server-side;
  4. then POSTs the payload to the Clay source with the source's auth token in x-clay-webhook-auth. Turn the token on for the source, so the URL alone no longer admits rows.

It can also set x-clay-webhook-idempotency-key to the envelope's idempotencyKey. Clay then keeps the latest payload for a repeated key instead of adding a row, so Evinor's delivery retries stop producing duplicates.

Treat the Clay source URL as a secret​

Without the auth token, the source URL alone admits rows. Anyone holding it can add rows and spend the table's Clay credits. Do not paste it into chat, tickets or shared documents. To rotate it, create a new source, update the destination, and delete the old source, because its URL keeps accepting rows until you do. A source accepts at most 50,000 submissions, and the count persists after rows are deleted, so a busy sensor eventually needs a new source. A new source also means a new URL to paste into the destination.

Pull: enrich a company list​

Create a Clay-only key​

Create a dedicated Evinor API key for Clay with exactly EVENTS_READ and REPORTS_READ (see Authentication). Do not reuse a key from anything else.

REPORTS_READ grants more than entity search. It also reads the key owner's reports, event types and reporting grants, and entity lookup. Those reads stay open to anyone who can use the key until you revoke it, so rotate it if the Clay workspace is shared with people who should not see your report data.

Store the key in a Clay HTTP API (Headers) account rather than typing it into the column. Clay stores account credentials encrypted, while headers typed into a column are visible to anyone with access to that column. Set the header to Authorization: Bearer followed by the key.

To revoke the key, open Settings → API keys in the Evinor web app.

Column 1: find the entity by domain​

Add an HTTP API column that calls:

GET https://api.evinor.ai/v1/entities/by-domain?domain=DOMAIN

Here DOMAIN is the column holding the company's website or domain. A full URL works: Evinor reduces https://www.acme.com/about to acme.com and echoes the reduced value back as domain. The key needs REPORTS_READ, and the call is not charged. See Looking up an entity by website domain for the rules.

The response lists the matching entities in data, each with an id, a name and the website Evinor has on record for it. Keep the whole response as the column's output, because the next columns read three cases from it:

  • data is empty: Evinor has no website on record on that domain. Column 2 falls back to a name search.
  • data has one entity: use its id.
  • data has more than one entity: several entities share the domain (for example a parent and its subsidiary, or a duplicate). The order is not a ranking, so do not take the first one blindly. Column 3 flags the row for review.

A row whose value is not a usable domain (an IP address, or a shared host such as linkedin.com or medium.com) returns 400 validation-failed. Clean those rows, or let them fall back to the name search too.

Add a second HTTP API column that runs only when column 1's data is empty (or column 1 returned 400), and calls:

GET https://api.evinor.ai/v1/entities/search?query=COMPANY_NAME&limit=5

Here COMPANY_NAME is the column holding the company's name. This call is not charged either. The response lists matches in data, each with an id.

A name search can match the wrong company. Several entities can share a name, and the first match is not always the one you mean. Name-matched rows deserve the same review as rows with several domain candidates.

Column 3: pick the entity id and flag rows for review​

Add two formula columns:

  • Entity ID: column 1's first data entry id when column 1's data has exactly one entry; otherwise column 2's first data entry id when column 1 found nothing (its data is empty, or it returned 400); otherwise empty.
  • Review: true when column 1's data has more than one entry, or when the id came from the name search in column 2.

Check the flagged rows before running the event search on them. For a row with several domain candidates, compare each candidate's name and website with the company you mean, and put the right id in the Entity ID column by hand.

Column 4: search its events​

Add an HTTP API column that calls:

POST https://api.evinor.ai/v1/events/search

with a JSON body such as:

{
"involved_entity_ids": ["ENTITY_ID"],
"lookback_days": 90
}

Here ENTITY_ID is the value of the Entity ID column from column 3. Run this column only on rows where Entity ID is set and Review is false (or has been checked), because each call is charged. The key needs EVENTS_READ. lookback_days is required when you send no cursor, and must be one of 7, 30, 90, 180 or 365. See Searching events for the filters and the response.

Each event in the response has an id, a sentence and a roles list. The roles entries use the keys role, text, amount, date and entity_id. These differ from the webhook's code, textValue, parsedAmount, parsedAmountUnit, parsedDate and namedEntityId, and amount is an object where the webhook sends a number and a unit, so do not reuse a push mapping for them.

Throughput​

Every call the Clay key makes counts against its rate limit, 60 requests per minute by default, shared by the columns that call the API: the domain lookup, the name-search fallback and the event search. The formula columns make no calls. Column 1 alone takes about 83 minutes for a 5,000-row list, and the name-search fallback and the event search add their own calls on top. A call over the limit returns 429 with a Retry-After header, so run a large list in batches.

Retries and the Idempotency-Key​

Clay re-runs an enrichment when a column it references changes, and a re-run that sends a fresh Idempotency-Key is a second charge. Derive the key from the row id plus the request body, so the same row and the same search always send the same key. See Idempotency.

  • Changed body, same key: 422 idempotency-key-conflict. Changing lookback_days on a row means a new key.
  • Same key and body, inside the replay window: the stored response comes back. It is not charged and it is not fresh: it is the earlier answer.
  • 402 before the charge: the key is released. Top up or raise the overage cap, then retry with the same key.
  • 502: Evinor does not know whether the charge committed, so it keeps the key claimed. A same-key retry then returns 409 idempotency-in-flight instead of charging again. That 409 is the protection, not an error to work around. Do not switch to a fresh key, because a fresh key is a new, separately charged search. Treat a repeating 502 as a support question.
  • No response at all (the request timed out or crashed): retry with the same key first. If the search finished after you gave up, you get its stored response without a second charge; if it is still running, a 409 turns into that replay once it finishes. Only if the original crashed does the 409 persist, because event search never reclaims an unfinished claim. Then a fresh key runs the search again and may charge again: do it on purpose, for that row only, by adding an attempt counter to the key. Never rotate keys automatically on a 409.

Cost​

  • Push: the sensor is charged per match. A delivery that never fires costs nothing.
  • Pull: each POST /v1/events/search without a cursor is charged EVENT_SEARCH_CREDIT_COST credits (1 credit today). A continuation, which sends only a cursor, is not re-charged. Entity lookups are not charged.
  • No overage cap: once your balance is spent, the next search returns 402.
  • With an overage cap: charges settle into overage up to the cap and are never billed beyond it. A 402 comes back once no room is left.
  • Concurrency: the check reads a balance snapshot, so many Clay cells running at once can all pass it before the balance updates and overshoot it. A charge the balance and cap cannot cover is recorded as deferred, not deducted.

Worked example. A 5,000-row list with one search per row costs up to 5,000 credits per run. Clay re-runs a cell when a column it uses changes. A re-run whose request body changed gets a new key and is charged at once, and an identical re-run is charged again once the 24-hour replay window has passed. Test on a few rows first, then check your balance and overage cap before choosing to run all.

Deduplicating​

Deduplicate pushed rows on payload.externalEventId, the underlying event id, as Receiving webhooks recommends. One event that matches several sensors arrives once per sensor with the same externalEventId.

Retries of one delivery share the same idempotencyKey, and a direct push has no way to tell Clay that. Each retry arrives as a new row. Deduplicate on payload.externalEventId, or use the verified path above to set Clay's idempotency header.