Webhook と API

ファイルやデータベースに住まないデータもあります — どこか別の場所から流れてきます。アプリがイベントを発行する。サードパーティサービスが webhook を発火。GraphQL エンドポイントが欲しいデータをちょうど持っているが誰も同期を書いていない。

Tablize はこれに 2 方向を提供:

• インバウンド: Webhook URL。 Tablize で URL を生成。どんなツールでもそれに POST すると行として着地。
• アウトバウンド: Agent が API を呼ぶ。 Agent はチャットターンから HTTP リクエスト — REST、GraphQL、カスタム — を発行可能。

インバウンド: Webhook URL

Webhook の作成

ワークスペース → Ingest → + New Webhook。得られるもの:

• 一意の URL（https://hook.tablize.com/w/<id>）。
• 検証可能な共有シークレット（X-Tablize-Sig ヘッダの HMAC-SHA256）。
• 宛先テーブル — 既存を選択するか Tablize に作成させる。
• 形 — フラット（ペイロードごとに 1 行）、配列（payload[] の要素ごとに 1 行）、ネスト（Agent が JSON 抽出器を書く）。

任意のサービスをその URL に向けます。Tablize は Content-Type: application/json または application/x-www-form-urlencoded の POST を受け入れます。JSON でないペイロードは raw JSONB カラムにそのまま保存。

スキーマ進化

最初のペイロードがテーブルスキーマを定義。追加フィールドのある後続ペイロードはそれらのフィールドが追加されます — データ削除なし、400 エラーなし。消えるフィールドは以降 NULL になるだけ。

真の破壊的変更（フィールド型が string から object へ反転）は _v2 テーブルを作成し、Agent がチャットで指摘。

重複排除

ほとんどの webhook ソースは再試行します。重複を防ぐには、冪等キー — 一意フィールドへの JSON パス — を宣言:

{"idempotency_key": "$.id"}

Tablize はそのフィールドでハッシュし、ローリング 7 日ウィンドウ内の重複を捨てます。

例: Shopify 注文 webhook

Shopify には（まだ）Tablize 統合がありませんが、統合をスキップして注文 webhook を直接パイプできます:

POST https://hook.tablize.com/w/abc123
X-Shopify-Topic: orders/create
{... 注文ペイロード ...}

Shopify は非 2xx で再試行。Tablize は 200 を高速（約 20ms）で返し、パースをキュー、行は数秒以内に data.shopify_orders に着地。

制限

プラン	ペイロードサイズ	受信 RPS（URL ごと）
Free	256 KB	1
Plus	1 MB	10
Pro	10 MB	100
Max	10 MB	1,000

RPS 上限超の webhook は 429。非常に大容量ソースには 統合 または前面のメッセージキューを使用。

アウトバウンド: Agent が API を呼ぶ

Agent には fetch ツールがあります。あなたが頼めば、呼びます。

> open-meteo から東京の天気を取得して

Agent は URL を構成し、リクエストを発行、レスポンスをパース、ナレーション。有用なら、呼び出しを Script として保存 — これでその API の名前付き再実行可能ラッパーがあります。

認証

Agent は 3 つの認証スタイルを尊重:

• 公開 API。 シークレット不要。Agent はただ呼びます。
• Bearer トークン / API キー。 ワークスペースの認証情報ボルトに保存。シークレットを追加し、名付け（例: OPENWEATHER_KEY）、チャットで参照: 「openweather キーを使って」。
• OAuth。 すでに OAuth サポートを構築した約 39 のサービスは 統合 を参照。それ以外は、サービス自身の UI で長寿命トークンを生成してシークレットとして保存。

シークレットはチャット履歴やログに現れません。Agent は不透明なハンドルとして見ます。HTTP レイヤーだけが実値を置き換えます。

GraphQL

Agent は GraphQL をネイティブに処理。エンドポイント + スキーマを指してクエリを頼む:

> shopify-admin graphql から直近 30 日の注文をください

クエリを書き、実行し、結果をローカルテーブルと JOIN。エンドポイントがイントロスペクションを無効化していたら、SDL を一度チャットに貼れば覚えます。

レート制限

Agent は Retry-After と X-RateLimit-* ヘッダを自動で尊重。カスタムスロットリングのある API には、ルールを自然言語で伝える — 「エンドポイントごと秒 5 リクエスト最大」 — と自身でペースを保ちます。

スケジュールプル

アウトバウンドパスをプルベース取り込みとしても使用可能: Agent に毎時取得して行をテーブルに保存するよう頼みます。Tablize は cron で取得を実行するスケジュールジョブを作成（Automation 参照）。Webhook と同じ冪等性ルール適用 — Script に冪等キーを追加すれば重複は捨てられます。

どちらを選ぶ: プッシュかプル？

• プッシュ（Webhook） はソースがすでに webhook を発火するときに正しい。低レイテンシ、あなたの時間が少ない。
• プル（Agent fetch） はソースが REST / GraphQL API だけを提供するとき、または取り込み時に変換したいときに正しい。

混在可能 — ホットパスにインバウンドペイロード、調整バックストップとしてスケジュール取得。

よくある落とし穴

• 署名検証失敗。 Webhook ソースは異なるアルゴリズムで署名。Tablize はデフォルトで X-Tablize-Sig を検証。ソース固有署名（Shopify、Stripe）には Webhook 設定で正しい検証器を切り替えてください。
• 「200 OK だが行なし」。 ペイロードが宣言した形に一致しなかった。Webhook の Recent deliveries タブを見る。任意の配信をクリックしてパース結果を見て、JSON パスを修正。
• Agent fetch がタイムアウト。 デフォルト HTTP タイムアウトは 15 秒。遅い API には、Agent に長いタイムアウトを使うよう頼む（「60 秒タイムアウトで再試行して」）か、ページネーション。
• スケジュール取得でレート制限ヒット。 スケジュールにジッタを追加、またはソースをより狭い取得に分割 — Agent は 429 を見ると両方を提案。

次のステップ

• 統合 — 同期がすでに構築された 39 サービス向け。
• ファイルをアップロード — すでに CSV やスプレッドシートとして持っているバッチデータ向け。
• Scripts — API 取得を再実行可能スクリプトとして保存。