stigg-webhooks

Stigg Webhook — イベントの受信と処理

Stigg は、サブスクリプションのライフサイクル、トライアルの移行、クレジット残高のしきい値、自動チャージの試行、エンタイトルメントの使用量超過など、変更があった際に Webhook でアプリに通知します。このスキルでは、Webhook の受信について説明します。エンドポイントの登録、正当性の検証、再試行への対応、ペイロードのエンベロープを扱います。

始める前に

親となる stigg スキルに従い、まず検索してください。 Webhook のイベント名とペイロードは変更される可能性があります。Mintlify Stigg docs MCP の query_docs_filesystem_stigg を使って /documentation/native-integrations/webhooks/events.mdx とイベントごとのリファレンスページを確認し、ハンドラーのコードを書く前に正確なペイロードのスキーマを確かめてください。

Webhook の登録

Stigg アプリで、Settings → Integrations → Webhooks → + New webhook を選択します。

フィールド	備考
サービス名	分かりやすいラベルです（例：「本番環境の Webhook」、「開発環境」）。
エンドポイント URL	ハンドラーの URL です（例：https://yourapp.com/api/stigg/webhooks）。Stigg が再試行するため、30 秒以内に 2XX を返す必要があります。
送信するイベント	カタログから選択します（サブスクリプション、トライアル、クレジット、エンタイトルメント、顧客など）。

作成した Webhook はすぐに有効になります。実際のイベントを接続する前に、特定のイベントの ⋮ メニューからテストイベントを送信して、ハンドラーを確認してください。

正当性 — シークレットを検証する

各 Webhook イベントには、次のヘッダーが含まれます。

Stigg-Webhooks-Secret: <secret>

このヘッダーの値を、Webhook の詳細ページに表示されるシークレットと照合します。両者は一致している必要があります。

HMAC 署名のサポートは Stigg のロードマップに含まれています。 現時点では、検証は単純なシークレット照合です。シークレットは API キーと同様に扱ってください（環境変数に設定し、ソースコードには決して含めないでください）。

ペイロードのエンベロープ

各 Webhook イベントには、次のトップレベルの構造があります（詳細はイベントごとに異なるため、イベントごとのページで確認してください）。

{
  "messageId": "msg_abc123",     // unique per event delivery — use for idempotency
  "type": "subscription.created", // event type
  "createdAt": "2026-01-15T10:30:00Z",
  "data": { /* event-specific payload */ }
}

フィールド名はイベントの種類によって多少異なる場合があります。必ず最新のイベントリファレンスページ（/documentation/native-integrations/webhooks/events.mdx およびイベントごとのサブページ）で確認してください。

冪等性 — messageId による重複排除

Stigg は同じイベントを複数回配信する場合があります（再試行、ネットワーク、エッジケースなど）。必ず次のように処理してください。

1. ペイロードから messageId を読み取ります。
2. 重複排除用ストア（Redis、DB の行、冪等性テーブル）で照合します。
3. すでに処理済みの場合は、すぐに 200 を返します。ハンドラーを再実行しないでください。
4. 新しいイベントの場合は処理してから、処理済みとして messageId を記録します。

配信順序は保証されません

Stigg は配信順序を保証しません。ハンドラーは順不同のイベントに対応できる必要があります。

• 時系列では後に発生した subscription.updated より先に、subscription.canceled が届く場合があります。
• 追加のクレジット付与がすでに発行された後に、credit.balance.depleted が届く場合があります。

順序が重要な場合は、イベントストリームから状態を再構築するのではなく、Stigg API から最新の状態を取得してください。

再試行の動作

エンドポイントが 2XX 以外を返すかタイムアウトした場合（30 秒超）、Stigg は再試行します。

1. すぐに 3 回再試行（バックオフなし）。
2. その後、30 秒ごとにさらに 3 回再試行します。

合計 6 回失敗すると、イベントは失敗となります。失敗したイベントは Stigg のバックエンドに保存され、リクエストに応じて再送信できます（サポートに連絡してください。セルフサービスの再送 UI はロードマップに含まれています）。また Stigg は、Webhook の配信失敗を積極的に監視し、失敗率が急上昇した場合は連絡します。

常にすばやく 200 を返してください。 受信を確認したら、処理を非同期でキューに入れます。複雑なロジックを同期的に処理するハンドラーは、30 秒のタイムアウトや不要な再試行を招くおそれがあります。

IP 許可リスト

Webhook イベントは Stigg の IP から送信されます。執筆時点では、18.119.35.43 です。リストは変更される可能性があります。固定する前に、/documentation/native-integrations/webhooks/index.mdx から再取得してください。

イベントカタログ（ドメイン別）

イベントの全リストは /documentation/native-integrations/webhooks/events.mdx にあります。正式な一覧を確認するには再取得してください。以下はドメイン別にまとめた一覧です。

ドメイン	主なイベント
顧客	customer.created、customer.updated、customer.deleted、customer.payment_failed、payment_method.attached、payment_method.detached
サブスクリプション	subscription.created、subscription.updated、subscription.canceled、subscription.creation_failed、subscription.expired_non_recurring、billing.month_ends_soon、subscription.spend_limit_exceeded
トライアル	trial.started、trial.ends_soon（有効期限の7日前）、trial.expired、trial.converted
エンタイトルメント	entitlement.usage_exceeded、entitlements.updated
クレジット — 残高	credit.balance.low、credit.balance.depleted
クレジット — 付与	credit.grant.created、credit.grant.updated、credit.grant.depleted、credit.grant.expired、credit.grant.balance_low
クレジット — 自動チャージ	automatic_recharge.operation.attempted、credits.automatic_recharge_limit_exceeded（上限の80／90／100％）、automatic_recharge.configuration.changed
プロモーションエンタイトルメント	promotional_entitlement.granted、promotional_entitlement.updated、promotional_entitlement.revoked、promotional_entitlement.expired、promotional_entitlement.ends_soon
カタログ	plan.created、plan.updated_new_version_published、plan.deleted、addon.created、addon.updated_new_version_published、addon.deleted、feature.created、feature.updated、feature.deleted、coupon.created、coupon.updated、coupon.archived
サードパーティ	third_party_sync_failed

正確なイベント名は変更される可能性があるため、必ずドキュメントで再確認してください。

ハンドラーのひな形（Next.js App Router + Node）

// app/api/stigg/webhooks/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { redis } from '@/lib/redis';

const SECRET = process.env.STIGG_WEBHOOK_SECRET!;

export async function POST(req: NextRequest) {
  // 1. Verify the secret
  const headerSecret = req.headers.get('Stigg-Webhooks-Secret');
  if (headerSecret !== SECRET) {
    return NextResponse.json({ error: 'Invalid secret' }, { status: 401 });
  }

  const event = await req.json();
  const { messageId, type, data } = event;

  // 2. Idempotency
  const seen = await redis.set(
    `stigg:webhook:${messageId}`,
    '1',
    { NX: true, EX: 60 * 60 * 24 * 7 }, // 7-day window
  );
  if (!seen) {
    return NextResponse.json({ ok: true, dedup: true }); // already processed
  }

  // 3. Acknowledge fast — queue heavy work async
  await queue.enqueue({ type, data });
  return NextResponse.json({ ok: true });
}

ハンドラーの処理は約500ms以内に完了させ、実際の作業はすべてワーカーで行ってください。Stigg が確認するのは2XXレスポンスのみです。

このスキルを使用しない場合

• Stigg API をアウトバウンドで呼び出す場合（プロビジョニング、ゲーティング、レポート）— stigg-api、stigg-subscriptions、stigg-entitlements、stigg-credits を使用してください。
• フロントエンドの状態変更（チェックアウト後のキャッシュ更新など）をリッスンする場合 — これは SDK の担当であり、Webhook の担当ではありません。
• Stigg MCP サーバーをセットアップする場合 — stigg-mcp を使用してください。

よくある間違い

間違い	対処法
署名検証を省略する	現時点で真正性を確認できるのは Stigg-Webhooks-Secret ヘッダーのみです。この値を照合してください。
ハンドラー内で同期的に処理する	すぐに2XXを返し、負荷の高い処理は非同期でキューに入れてください。同期処理では30秒のタイムアウトが発生するおそれがあります。
イベントの順序を前提にする	Stigg は順序を保証しないことを明示しています。順不同を許容するか、API から最新の状態を取得してください。
messageId に対する冪等性がない	Stigg は失敗時に再試行します。重複排除を行わないと、同じイベントを2回処理してしまいます。
IP 許可リストだけを唯一のチェック方法として信頼する	IP リストは変更される可能性があります。IP 許可リストとシークレットの検証を両方使用してください。
「認識できないイベント」に対して4XXを返す	再試行が発生します。2XXを返し、不明なイベントタイプは通知せずに無視してください。
HMAC 検証を手動で実装する	HMAC サポートはまだ提供されておらず、ロードマップ上の項目です。現時点での取り決めは、プレーンなシークレットの照合です。
配信失敗に対応しない	Stigg の6回の試行スケジュールで失敗した場合、イベントは保存されますが、自動で再配信されません。再送信についてはサポートに問い合わせてください。また、失敗が継続した場合に備えて、運用アラートを構築してください。
Webhook を唯一の信頼できる情報源として扱う	順序は保証されず、再配信もセルフサービスではありません。Webhook と併せて、Stigg API に対する定期的な状態照合を行ってください。
「すべてのイベント」を購読する	通知が多くなり、受信側の負荷も増えます。実際に処理するイベントだけを選んでください。