gocardless-webhooks

GoCardless Webhooks

GoCardless は、銀行口座振替と継続課金のプラットフォームです。events 配列に最大 250 件のイベントを含むバッチとして Webhook を送信し、Webhook-Signature ヘッダーの HMAC-SHA256 署名で保護します。

このスキルを使用する場面

• GoCardless の Webhook を受信するにはどうすればよいですか？
• GoCardless の Webhook-Signature ヘッダーを検証するにはどうすればよいですか？
• GoCardless の Webhook 署名の検証に失敗するのはなぜですか？
• payments の confirmed／failed、mandates の cancelled、または payouts の paid イベントを処理するにはどうすればよいですか？
• GoCardless の events 配列を冪等に処理するにはどうすればよいですか？

GoCardless による Webhook 署名の仕組み

• ヘッダー： Webhook-Signature — 64 文字の小文字の 16 進ダイジェスト（X- プレフィックスや sha256= スキームプレフィックスはありません）
• アルゴリズム： 未加工のリクエスト本文に対する HMAC-SHA256。キーには Webhook エンドポイントのシークレット（GoCardless Dashboard で取得）を使用します
• キー： シークレットはそのまま UTF-8 文字列として使用してください。base64url のように見えても、base64 デコードしてはいけません。デコードすると署名が一致しなくなります
• エンコード： 小文字の16 進数文字列
• 比較： タイミングセーフな等価比較
• レスポンス： バッチ全体を受け付けたら 204 No Content を返します。2xx 以外のレスポンス（例：498）は配信失敗として扱われます。GoCardless は自動再試行を行いません。再配信は手動で実行します（POST /webhooks/{id}/actions/retry）。配信は少なくとも 1 回行われるため、ハンドラーは event.id に対して冪等にしてください。

(2026-08 に、ライブサンドボックスへの配信と公式の gocardless-nodejs SDK を使って方式を検証しました。GoCardless の説明には、現在もアルゴリズムが明記されていません。)

必ず未加工の本文に対して検証してください。先に JSON を解析して再シリアライズすると、バイト列が変わり署名が一致しなくなります。

検証（基本）

利用可能な環境（Node.js）では、公式の gocardless-nodejs SDK を使用してください。parse() は署名を検証（タイミングセーフ）してイベント配列を返します。署名が一致しない場合は InvalidSignatureError をスローします。

// Node.js — official SDK (gocardless-nodejs), req.body is the RAW Buffer
const { parse, InvalidSignatureError } = require('gocardless-nodejs/webhooks');

try {
  const events = parse(
    req.body,                                  // raw body (Buffer/string), NOT parsed JSON
    process.env.GOCARDLESS_WEBHOOK_SECRET,     // webhook endpoint secret
    req.headers['webhook-signature']           // Webhook-Signature header
  );
  // signature valid — process each event, then respond 204
} catch (err) {
  if (err instanceof InvalidSignatureError) {
    // signature mismatch — respond 498 (do not process)
  }
}

GoCardless SDK がない言語（例：Python/FastAPI）では、同じアルゴリズムを使い、タイミングセーフな比較で手動検証してください。

import hmac, hashlib
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(expected, signature_header)  # timing-safe

テスト付きの完全なハンドラーについては、 examples/express/、examples/nextjs/、examples/fastapi/ を参照してください。

一般的なイベントタイプ

GoCardless のイベントは、resource_type と action の組み合わせです。主なものは次のとおりです。

resource_type	action	発生するタイミング
payments	confirmed	顧客からの資金回収が確定したとき
payments	paid_out	支払いが銀行口座への入金に含まれたとき
payments	failed	支払いに失敗したとき（例：残高不足）
payments	cancelled	支払いが送信前にキャンセルされたとき
payments	charged_back	顧客が支払いに対してチャージバックしたとき
mandates	active	マンデートの設定が完了し、回収可能になったとき
mandates	customer_approval_granted	顧客がマンデートを承認したとき（ライブ環境で確認済み）
mandates	cancelled	マンデートがキャンセルされたとき（例：銀行口座が閉鎖された）
mandates	failed	マンデートの設定に失敗したとき
mandates	expired	利用がないままマンデートの有効期限が切れたとき
payouts	paid	銀行口座への入金が送金されたとき
refunds	paid	顧客への返金が送信されたとき
refunds	failed	返金に失敗したとき
subscriptions	created	サブスクリプションが作成されたとき
subscriptions	cancelled	サブスクリプションがキャンセルされたとき

リソースタイプごとのアクション一覧については、overview.md を参照してください。

環境変数

# Webhook endpoint secret from the GoCardless Dashboard (Developers → Webhook endpoints)
GOCARDLESS_WEBHOOK_SECRET=your_webhook_endpoint_secret

ローカル開発

ローカルで Webhook をテストするには、インストール不要の npx 経由で Hookdeck CLI を実行します。

npx hookdeck-cli listen 3000 gocardless --path /webhooks/gocardless

アカウントは不要です。CLI は初回実行時にゲストアカウントを作成し、リクエストを確認できるローカルトンネルと Web UI を提供します。FastAPI の例ではポート 8000 を使用してください。

参考資料

• 概要 - GoCardless Webhook の概要、イベントとアクションの全リスト
• セットアップ - Webhook エンドポイントを作成し、シークレットをコピーする方法
• 検証 - 署名検証の詳細と注意点

例

• Express の例 - GoCardless SDK を使用した Express 5 のハンドラーとテスト
• Next.js の例 - GoCardless SDK を使用した Next.js App Router のルートとテスト
• FastAPI の例 - 手動 HMAC 検証を行う Python FastAPI ハンドラーとテスト

推奨：webhook-handler-patterns

このスキルと併せて webhook-handler-patterns スキルをインストールすることをおすすめします。GoCardless は自動再試行を行いません（再配信は手動です）が、配信は少なくとも 1 回行われるため、冪等性が重要です。主な参考資料（GitHub で開いてください）：

• ハンドラーの順序 — 最初に検証し、次に解析し、その後に冪等性を保って処理します
• 冪等性 — 重複処理を防ぎます（event.id で重複排除します）
• エラー処理 — 戻りコード、ログ記録、デッドレターキュー
• 再試行ロジック — プロバイダーの再試行スケジュール、バックオフパターン

関連スキル

• stripe-webhooks - Stripe の決済 Webhook 処理
• paddle-webhooks - Paddle の請求 Webhook 処理
• chargebee-webhooks - Chargebee のサブスクリプション請求 Webhook 処理
• paypal-webhooks - PayPal の決済 Webhook 処理
• shopify-webhooks - Shopify の eコマース Webhook 処理
• github-webhooks - GitHub リポジトリの Webhook 処理
• webhook-handler-patterns - ハンドラーの順序、冪等性、エラー処理、再試行ロジック
• hookdeck-event-gateway - キューに代わる Webhook インフラストラクチャ — 配信保証、自動再試行、再生、レート制限、Webhook ハンドラーの可観測性を提供します