「繋いで効かせる DX」のための、API 連携設計

Introduction — 基幹を作り直さない DX

SMB (中小企業) の DX で「基幹システムを丸ごと入れ替える」という選択肢を取れるケースは多くありません。 既存の会計・顧客管理・在庫・EC が動いている以上、現実的な打ち手は「既存を残したまま、SaaS を API で繋いで効かせる」ことです。

Xiora 自身が採用している内製システム (XAISeoAutomation = ConoHa v3 DNS + Google OAuth + GA4 Admin API 統合、XAIOutreach = Gmail SMTP + IMAP 統合) も、同じ考え方で作っています。 本記事では、その実装から抽出した 4 つの設計原則と、Webhook 受信で押さえるべき論点を共有します。

4 つの設計原則

1. 冪等性 (Idempotency)

同じ request を N 回送っても最終状態が変わらないこと。 これは HTTP の基本設計 (RFC 9110 では GET / PUT / DELETE が冪等メソッドと定義) に沿った考え方で、SaaS 側の実装としては Stripe の Idempotency-Key header が代表例です (公式: Idempotent requests)。

Xiora の実装では、外部 API を叩く operation ごとにアプリ側で UUIDv4 を採番し、DB に「送信済み key」を残す運用にしています。 再送が発生しても Stripe 側で 24 時間は同じ結果が返るため、ネットワークタイムアウト後の再試行で二重課金が起きません。

2. 再送設計 (Retry with backoff)

外部 API は本番運用に乗せた瞬間に失敗が観測されます。 5xx や 429 (Too Many Requests) は「一時的な失敗」なので、指数バックオフ + jitter で再送するのが定石です (AWS Architecture Blog: Exponential Backoff And Jitter)。

Xiora の brain runtime では、attempt に対して min(cap, base * 2^attempt) + random(0, jitter) の待機を挟み、max_attempts = 5 で打ち切ってからは Dead Letter Queue (再処理待ちテーブル) に落として運用側の確認に回します。 4xx (認証失敗・validation error) は再送せず即 fail するのが原則です。

3. 計測 (Observability)

「なぜ失敗したか」を後から追えなければ、連携は属人化します。 最低限、request_id / endpoint / status_code / latency_ms / error_code / attempt の 6 項目を構造化ログで残し、外部 API のコスト (呼び出し数 × 単価) も日次で集計します。 Xiora では xioraai-postgres の共通テーブルに集約し、ダッシュボードで異常値 (エラー率急増・latency spike) を可視化しています。

4. 運用責任 (Ownership)

技術面が完璧でも、運用の窓口が決まっていない連携は障害時に沈黙します。 SaaS ごとに「SLA / 障害時の一次対応者 / secret rotation の担当と周期 / breaking change 通知の受信先」を最低限ドキュメント化しておきます。 Xiora では ConoHa API password / Google refresh_token / Stripe restricted key を 90 日で rotation する運用にしています。

Webhook 受信の 5 論点

こちらから叩く API と対になるのが、SaaS 側から呼ばれる Webhook です。 実装時に押さえるべきは以下の 5 点です。

1. 署名検証 — 受信 body の HMAC-SHA256 署名を検証。 Stripe は Stripe-Signature header と whsec_... secret (公式)、GitHub は X-Hub-Signature-256 (公式)、Slack は X-Slack-Signature + X-Slack-Request-Timestamp (公式)
2. 冪等 event_id — SaaS 側は re-delivery を行う前提。 Stripe / GitHub とも event に一意 ID があり、受信側で処理済みかを DB でチェック
3. 順序保証なし — HTTP 経由の Webhook は到着順が入れ替わる。 順序が重要な処理は event timestamp を基準に並べ替え
4. retry 前提の応答 — 2xx を返さないと SaaS 側が再送。 重い処理は queue に積んで即 200 を返し、非同期で処理
5. stateless — 受信 endpoint 自体はローカル state を持たず、必要な情報はすべて event に含まれる前提で書く

SaaS 間で「壊れやすい繋ぎ」パターン

• 認証情報の rotation 忘れ — refresh_token / API key の失効で突然止まる。 secret manager 側に有効期限を持たせて事前通知
• rate limit 到達 — 平常時の 3-5 倍のバーストで簡単に頭打ち。 予備として local queue とバックプレッシャを組む
• breaking change — SaaS 側の API バージョンアップで silent break。 常にバージョン pinned + release note を購読

免責 / 参考リンク

• 本記事は 2026-07-19 時点の公開仕様に基づく整理です。 各サービスの実装は最新の公式ドキュメントをあわせて参照してください
• RFC 9110 HTTP Semantics: https://www.rfc-editor.org/rfc/rfc9110.html
• Stripe Idempotent requests: https://docs.stripe.com/api/idempotent_requests
• AWS Architecture Blog — Exponential Backoff And Jitter: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
• Stripe Webhooks — Verify signatures: https://docs.stripe.com/webhooks/signature
• GitHub Webhooks — Validating deliveries: https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
• Slack — Verifying requests: https://api.slack.com/authentication/verifying-requests-from-slack

---