mp-webhooks

mp-webhooks

このスキルは通知に関するあらゆることを扱います。HMAC 検証パターンが存在する唯一の場所であり、他のすべてのスキルはここに委ねます。

---

ステップ 0 — MCP を利用するアクションの場合のみ接続する

このスキルが開始した時点で、MCP の状態を検査しないでください。レシーバーパターンの雛形作成とレビューは静的な操作であり、MCP 接続を必要としません。

接続するのは、以下に挙げる選択された操作の直前に限られます。

操作	必要な MCP ツール
言語固有の署名サンプルを取得する	search_documentation
不明なトピックや国固有のトピックを解決する	search_documentation
コールバック URL を登録またはローテーションする	save_webhook
webhook の配信を確認または診断する	notifications_history

オンデマンドの認証手順:

1. 呼び出し可能であれば、目的のツールを直接試してください。接続の確認として application_list を呼び出さないでください。
2. ツールが利用できない、または認証エラーを返す場合は、mcp__plugin_mercadopago_mcp__authenticate を呼び出してください。
3. クリック可能な OAuth リンクを開発者の言語で表示し、URL を外部ブラウザーにコピーせずに、Cmd+Click（Mac）または Ctrl+Click（Windows/Linux）するよう指示してください。
4. 開発者が戻ったら、目的のツールを直接再試行してください。コールバック URL を貼り付けるよう決して求めないでください。
5. MCP ツールが読み込まれていない場合は、plugin:mercadopago:mcp を有効にする方法を説明してください。静的な雛形作成/レビューの作業はオフラインでも利用可能なままにしてください。

この前提条件チェックリストは、開発者が MCP を利用するアクションを選択した場合にのみ表示してください:

Before configuring webhooks live, you'll need:
- [ ] A Mercado Pago developer account
- [ ] An app created in the Developer Dashboard
- [ ] Test credentials: APP_USR- access token + public key (tab {test_tab})
- [ ] The webhook signature secret (Dashboard → Webhooks → Signature secret)
Connection will be requested immediately before the selected MCP operation.

---

ステップ 1 — アクションを決定する

開発者に（または $ARGUMENTS から推測して）次のどれを望んでいるか尋ねてください:

アクション	呼び出すツール	タイミング
MP アプリケーションで webhook URL を設定する	save_webhook	初回セットアップ時またはエンドポイントのローテーション時
配信失敗を診断する	notifications_history	見逃した/失敗した通知を調査するとき
レシーバーコードの雛形を作成する	(MCP 呼び出しなし — 以下のパターンをレンダリングします)	レシーバーをコードベースに追加するとき

これらを連鎖させてもかまいません: レシーバーの雛形作成 → save_webhook → 実際のテスト決済をトリガー → notifications_history で配信を確認。

---

ステップ 2 — レシーバーパターン（HMAC-SHA256）

Mercado Pago は、ダッシュボードの Webhooks → Signature secret で返されるシークレットで、すべての通知に署名します。x-signature ヘッダーは ts=...,v1=... で構成され、v1 は正規文字列 "id:{data.id};request-id:{x-request-id};ts:{ts};" の HMAC-SHA256 です。

すべてのレシーバーは必ず次のことを行う必要があります:

1. リクエストヘッダーから x-signature と x-request-id を読み取る。
2. x-signature から ts と v1 を解析する。
3. data.id（JSON ボディから）と x-request-id と ts で正規文字列を構築する。
4. HMAC-SHA256(canonical, secret) を計算し、v1 と定数時間で比較する。
5. 署名が有効であれば直ちに 200 を応答する — その後でイベントを非同期に処理します。Mercado Pago は 200 以外の応答に対して、最大約 24 時間、指数バックオフで再試行します。
6. 冪等であること: 同じ通知 ID が複数回届く可能性があります。data.id + トピックを重複排除キーとして使用してください。

正規文字列

id:<data.id>;request-id:<x-request-id>;ts:<ts>;

リファレンススニペット（Node.js、Express）

import crypto from "node:crypto";

const SECRET = process.env.MP_WEBHOOK_SECRET;

export function mpWebhook(req, res) {
  const signature = req.header("x-signature") ?? "";
  const requestId = req.header("x-request-id") ?? "";
  const parts = Object.fromEntries(
    signature.split(",").map((p) => p.split("=").map((s) => s.trim()))
  );
  const ts = parts.ts;
  const v1 = parts.v1;
  const dataId = req.body?.data?.id;
  if (!ts || !v1 || !dataId || !requestId) return res.status(400).end();

  const canonical = `id:${dataId};request-id:${requestId};ts:${ts};`;
  const expected = crypto.createHmac("sha256", SECRET).update(canonical).digest("hex");

  const ok = expected.length === v1.length &&
             crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
  if (!ok) return res.status(401).end();

  res.status(200).end();
  // process asynchronously after responding 200
  queueMicrotask(() => handleEvent(req.body));
}

他の言語については、MCP の search_documentation を次のクエリで照会する直前にステップ 0 を適用してください:

• "webhook signature validation {language}"（例: python、java、php、ruby、go、dotnet）。

---

ステップ 3 — トピック

通知のボディには type(トピック)と data.id が含まれます。一般的なトピックは次のとおりです。

トピック	タイミング	取得するリソース
payment	決済ステータスの変更(Payments API)	GET /v1/payments/{id}
orders	ポイント / QR コードのイベント(Orders API)	GET /v1/orders/{id}
merchant_order	マーチャントオーダーの更新 — レガシー(Checkout Pro / QR 対面はレガシー API 経由)	GET /merchant_orders/{id}
topic_claims_integration_wh	チャージバック	GET /v1/chargebacks/{id}
point_integration_wh	ポイントデバイスのイベント — レガシー(旧 Point Integration API)	Point レガシー API — 国を MCP に問い合わせてください
subscription_preapproval	サブスクリプションのステータス変更	GET /preapproval/{id}
subscription_authorized_payment	定期課金の試行	GET /authorized_payments/{id}

トピックがこの表にない場合は、推測せず、MCP に最新の一覧を問い合わせる直前にステップ 0 を適用してください。

---

ステップ 4 — Mercado Pago での設定(save_webhook)

オンデマンドで接続: save_webhook の直前にステップ 0 を適用してください。最初に application_list を呼び出さないでください。

mcp__plugin_mercadopago_mcp__save_webhook(
  callback="https://<production-url>/mp/webhook",
  callback_url="https://<your-domain>/mp/webhook",
  topics=["payment", "merchant_order", ...]
)

レスポンスに URL とトピックが正しく登録されていることを確認してください。

---

ステップ 5 — スモークテスト(実際のテスト決済)

simulate_webhook は MCP に存在しなくなりました。受信側をテストするには:

1. テスト用認証情報 + テストユーザー + テストカードで実際の決済を行います
2. 決済ステータスが変更されると、Webhook が自動的に発火します
3. 受信側が 200 を返し、イベントを冪等に処理したことを確認します

配信を確認するために notifications_history を使用する直前に、ステップ 0 を適用してください:

mcp__plugin_mercadopago_mcp__notifications_history()

---

ステップ 6 — 配信漏れの診断

オンデマンドで接続: notifications_history の直前にステップ 0 を適用してください。最初に application_list を呼び出さないでください。

mcp__plugin_mercadopago_mcp__notifications_history()

配信メトリクスと、失敗の内訳(タイムアウト、非 200 レスポンス、署名の不一致)を返します。本番環境で通知が届かない場合に使用してください。

---

注意点

• 処理の前に 200 を返してください。長時間実行される同期ハンドラーは、受信側にあふれるほどのリトライを引き起こし、本当の失敗を覆い隠す可能性があります。
• Mercado Pago は非 200 の場合、最大約 24 時間まで指数バックオフでリトライします — 一時的なバグが大量の重複になります。
• ハンドラーを冪等にしてください。data.id + type を重複排除キーとして使用してください。
• JSON ボディだけを決して信用しないでください — 必ず最初に署名を検証してください。
• IPN(レガシーの ?id=&topic= GET 形式の通知)は非推奨です。新しい統合では、ここで説明する最新の署名付き Webhook のみを使用します。

---

このスキルが行わないこと

• 周辺の統合をスキャフォールドしません。mp-integrate を使用してください。
• 品質を評価しません。mp-review を使用してください。
• 記憶からトピック名をでっち上げません — 不明な場合は MCP に問い合わせてください。