Write path
gtm-sdk writes to Clay tables through each table’s webhook endpoint. The webhook accepts JSON and can be protected with a per-table token sent in thex-clay-webhook-auth header. The implementation keeps that token in Infisical
and never puts it in a row or log payload.
The Clay Public API is not a replacement for this write path. Clay’s current
developer platform can query known Enterprise tables, but table writes and
table-building are not supported. The Tables API is therefore useful for
read-only reconciliation, not for checking-and-creating rows.
Authentication and API capabilities
Public API keys are server-side credentials. Store them in the secret manager
if a future reconciliation job needs them. The Tables API has no list-tables
operation, so table IDs must be configured explicitly.
Duplicate handling
Every exported row must contain a deterministic, non-emptyevent_id. RB2B
uses its source event ID and Octolens derives an ID from the source and source
record ID. The value is intentionally stable across transport retries and is
the column Clay should use for auto-dedupe.
Configure Clay auto-dedupe on event_id and keep the oldest row by default.
Clay compares exact strings, including case and whitespace, so producers must
not normalize or reformat an ID between attempts. Auto-dedupe is eventual: a
retry can still be accepted and processed before Clay removes the duplicate.
The webhook sender therefore treats a successful HTTP response as delivery,
not as proof of exactly-once enrichment.
A durable idempotency store before post_row dedupes redeliveries; extend it
if exactly-once Clay processing becomes a requirement. Do not implement a
Public API read-before-write check: it is race-prone and the Public API does
not provide a table upsert endpoint.
Capacity and operations
Clay webhook sources have a 50,000-submission limit that persists after rows are deleted. Enterprise passthrough/auto-delete tables can process and forward rows before deleting them, avoiding that fixed accumulation limit. Confirm the selected Clay plan supports auto-dedupe, passthrough, and API-enabled tables before production rollout. The implementation validatesevent_id, retries Clay HTTP failures rather
than surfacing them to the caller, and logs the event ID and response status
without logging the webhook token. Controlled validation should cover
duplicate deliveries, distinct IDs, case/whitespace changes, HTTP failures,
and retry behavior.
References: Clay API & CLI,
Quickstart,
Tables API,
Webhooks, and
table management.