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
| Path | How it works | Best for | Cost |
|---|---|---|---|
| Push | A 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. |
| Pull | HTTP 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
- In Clay, open a workbook and choose + Add, then Webhooks, then
Monitor webhook. Copy the webhook URL. Each JSON
POSTto it updates the table. - In the Evinor web app, open the sensor's Delivery step, add a Webhook destination and paste the Clay URL. See Receiving webhooks.
- To see a row before a real event arrives, send a test delivery. Call
POST /v1/sensors/{id}/test-deliverieswith a separate key that hasSENSORS_WRITE, never the Clay key, and the Clay URL asurlin 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. - Map fields from the delivery into columns:
| Field | What it holds |
|---|---|
payload.details.generatedSentence | A 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.externalEventId | The 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:
- rejects unsigned or invalid deliveries (see Signature verification);
- rejects stale timestamps and any
idempotencyKeyit has already processed (see Replay protection); - keeps the Clay URL server-side;
- then
POSTs the payload to the Clay source with the source's auth token inx-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:
datais empty: Evinor has no website on record on that domain. Column 2 falls back to a name search.datahas one entity: use itsid.datahas 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.
Column 2: fall back to a name search
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
dataentryidwhen column 1'sdatahas exactly one entry; otherwise column 2's firstdataentryidwhen column 1 found nothing (itsdatais empty, or it returned400); otherwise empty. - Review: true when column 1's
datahas 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:
422idempotency-key-conflict. Changinglookback_dayson 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.
402before 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 returns409idempotency-in-flightinstead of charging again. That409is 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 repeating502as 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
409turns into that replay once it finishes. Only if the original crashed does the409persist, 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 a409.
Cost
- Push: the sensor is charged per match. A delivery that never fires costs nothing.
- Pull: each
POST /v1/events/searchwithout acursoris chargedEVENT_SEARCH_CREDIT_COSTcredits (1 credit today). A continuation, which sends only acursor, 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
402comes 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.