Webhooks & APIs

Some data doesn’t live in a file or a database — it flows in from somewhere else. Your app emits events. A third-party service fires webhooks. A GraphQL endpoint has exactly the data you want but nobody’s written the sync yet.

Tablize gives you two directions for this:

• Inbound: Webhook URLs. You generate a URL in Tablize; whatever tool posts to it lands as rows.
• Outbound: the Agent calls APIs. The Agent can issue HTTP requests — REST, GraphQL, or custom — from a chat turn.

Inbound: Webhook URLs

Creating a Webhook

Workspace → Ingest → + New Webhook. You get:

• A unique URL (https://hook.tablize.com/w/<id>).
• A shared secret you can verify against (HMAC-SHA256 in the X-Tablize-Sig header).
• A destination table — pick existing or let Tablize create one.
• A shape: flat (one row per payload), array (one row per element in payload[]), or nested (the Agent writes a JSON extractor).

Point any service at that URL. Tablize accepts POST with Content-Type: application/json or application/x-www-form-urlencoded. Non-JSON payloads are stored as-is in a raw JSONB column.

Schema evolution

The first payload defines the table schema. Subsequent payloads with extra fields get those fields added — no dropped data, no 400 errors. Fields that disappear just become NULL going forward.

Truly breaking changes (a field’s type flips from string to object) create a _v2 table and the Agent points it out in chat.

Deduplication

Most webhook sources retry. To prevent duplicates, declare an idempotency key — a JSON path to a unique field:

{"idempotency_key": "$.id"}

Tablize hashes on that field and drops duplicates within a rolling 7-day window.

Example: Shopify orders webhook

Shopify doesn’t have a Tablize integration (yet), but you can skip the integration and pipe the orders webhook directly:

POST https://hook.tablize.com/w/abc123
X-Shopify-Topic: orders/create
{... order payload ...}

Shopify retries on non-2xx. Tablize returns 200 fast (~20ms), queues the parse, and the row lands in data.shopify_orders within seconds.

Limits

Plan	Payload size	Inbound RPS (per URL)
Free	256 KB	1
Plus	1 MB	10
Pro	10 MB	100
Max	10 MB	1,000

Webhooks above the RPS ceiling 429. For very high-volume sources, use an Integration or a message queue in front.

Outbound: the Agent calls APIs

The Agent has a fetch tool. You ask, it calls.

> get the weather for Tokyo from open-meteo

The Agent composes the URL, issues the request, parses the response, and narrates. If it’s useful, save the call as a Script — now you have a named, rerunnable wrapper around that API.

Authentication

The Agent honors three auth styles:

• Public APIs. No secret needed. The Agent just calls.
• Bearer tokens / API keys. Stored in the workspace’s credential vault. Add a secret, name it (e.g. OPENWEATHER_KEY), reference it in chat: “use the openweather key.”
• OAuth. For the ~39 services where we’ve already built OAuth support, see Integrations. For everything else, generate a long-lived token in the service’s own UI and store it as a secret.

Secrets never appear in chat history or logs. The Agent sees them as opaque handles; only the HTTP layer substitutes the real value.

GraphQL

The Agent handles GraphQL natively. Point it at an endpoint + schema and ask for a query:

> give me the last 30 days of orders from shopify-admin graphql

It’ll write the query, run it, and join the result with any local table you have. If the endpoint has introspection disabled, paste the SDL into the chat once and it’ll remember.

Rate limits

The Agent respects Retry-After and X-RateLimit-* headers automatically. For APIs with custom throttling, tell it the rule in plain English — “max 5 requests per second per endpoint” — and it’ll pace itself.

Scheduled pulls

You can also use the outbound path as a pull-based ingest: ask the Agent to fetch every hour and save the rows to a table. Tablize creates a Scheduled Job (see Automation) that runs the fetch on cron. Same idempotency rules as Webhooks apply — add an idempotency key to the Script and dupes are dropped.

Pick one: push or pull?

• Push (Webhook) is right when the source already fires webhooks. Lower latency, less of your time.
• Pull (Agent fetch) is right when the source only offers a REST / GraphQL API, or when you want to transform on the way in.

You can mix and match — inbound payloads for the hot path, scheduled fetches as a reconciliation backstop.

Common gotchas

• Signature verification failing. Webhook sources sign with different algorithms. Tablize validates X-Tablize-Sig by default; for source-specific signatures (Shopify, Stripe), toggle the right verifier in the Webhook settings.
• “200 OK but no row.” Your payload didn’t match the shape you declared. Look at the webhook’s Recent deliveries tab; click any delivery to see the parse result and fix the JSON path.
• Agent fetches timing out. Default HTTP timeout is 15 seconds. For slow APIs, ask the Agent to use a longer timeout (“try again with a 60-second timeout”) or paginate.
• Hitting rate limits on a scheduled fetch. Add jitter to the schedule or split the source into narrower fetches — the Agent will suggest both when it sees 429s.

Next steps

• Integrations — for 39 services where the sync is already built.
• Upload files — for batch data you already have as CSVs or spreadsheets.
• Scripts — save an API fetch as a rerunnable script.