> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook の更新

> Webhook の URL、イベント、または secret を更新する

既存の Webhook の URL、購読イベント、またはチャネル固有の secret を更新します。`channel` と `testMode` フィールドは不変です — 変更するには Webhook を削除して再追加してください。

```
POST /v1/actions/store/update-webhook
```

**認証：** API Key（owner または admin ロールが必要）

## リクエストボディ

| フィールド    | 型              | 必須  | 説明                                                                   |
| -------- | -------------- | --- | -------------------------------------------------------------------- |
| `id`     | string         | Yes | Webhook UUID（`add-webhook` または GraphQL `Store.storeWebhooks` から返される） |
| `url`    | string         | No  | 送信先 URL を置き換えます。                                                     |
| `events` | string\[]      | No  | 購読イベントタイプを置き換えます                                                     |
| `secret` | string \| null | No  | チャネル固有の認証情報を置き換えます。クリアするには `null` を渡します。                             |

<Note>
  `channel` は特定の Webhook レコードに対して恒久的です — チャネルを切り替えるには、削除して再追加してください。URL の変更はそのまま受け入れられます。マーチャントは新しい URL がチャネルと一致することを保証してください。
</Note>

## リクエスト例

<CodeGroup>
  ```typescript SDK theme={"system"}
  import { WaffoPancake } from "@waffo/pancake-ts";

  const client = new WaffoPancake({
    merchantId: process.env.WAFFO_MERCHANT_ID!,
    privateKey: process.env.WAFFO_PRIVATE_KEY!,
  });

  // Add more events to an existing webhook
  await client.webhooks.update({
    id: "11111111-2222-3333-4444-555555555555",
    events: ["order.completed", "refund.succeeded", "subscription.canceled"],
  });
  ```

  ```bash cURL theme={"system"}
  curl -X POST https://api.waffo.com/v1/actions/store/update-webhook \
    -H "Content-Type: application/json" \
    -H "X-Merchant-Id: $WAFFO_MERCHANT_ID" \
    -H "X-Signature: ..." \
    -d '{
      "id": "11111111-2222-3333-4444-555555555555",
      "events": ["order.completed", "refund.succeeded"]
    }'
  ```
</CodeGroup>

## 成功レスポンス (200)

更新された Webhook エンティティを返します。形状は [`add-webhook`](/ja/api-reference/endpoints/webhooks/add-webhook#成功レスポンス-200) と同じです。

## レスポンスフィールド

| フィールド       | 型              | 説明                                        |
| ----------- | -------------- | ----------------------------------------- |
| `id`        | string         | Webhook UUID                              |
| `storeId`   | string         | 所属ストアの UUID                               |
| `channel`   | string         | Webhook チャネル（不変）                          |
| `url`       | string         | 送信先 Webhook URL                           |
| `events`    | string\[]      | 購読するイベントタイプ                               |
| `testMode`  | boolean        | `true` はテストトランザクションで発火、`false` は本番で発火（不変） |
| `secret`    | string \| null | チャネル固有の認証情報、クリア済みの場合は `null`              |
| `createdAt` | string         | 作成タイムスタンプ（ISO 8601）                       |
| `updatedAt` | string         | 最終更新タイムスタンプ（ISO 8601）                     |

## エラー

> **リトライポリシー**：4xx は一切リトライしない — リクエストを修正してから再送信。5xx は指数バックオフでリトライ（5s 開始、最大 3 回）。

| ステータス | `errors[0].message`                                | 意味                                                     | 推奨処理                                          |
| ----- | -------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------- |
| 400   | `Missing required field: id`                       | `id` が指定されていない                                         | リクエストボディを修正して再送信                              |
| 400   | `id must be a valid UUID`                          | `id` が有効な UUID ではない                                    | `id` を修正して再送信                                 |
| 400   | `Invalid URL format`                               | `url` が有効な URL として解析できない                               | URL フォーマット（HTTPS、有効な URL）を修正して再送信             |
| 400   | `events must be a string array`                    | `events` が文字列の JSON 配列ではない                             | `events` を文字列配列として送信（例：`["order.completed"]`） |
| 400   | `secret must be a string or null`                  | `secret` が string でも `null` でもない                       | string 値、またはクリアする場合は `null` を送信               |
| 403   | `Not authorized to manage webhooks for this store` | 呼び出し元の所属ストアにおける merchant ロールが `owner` または `admin` ではない | 必要なロールを持つ API Key に切り替え                       |
| 404   | `Webhook not found`                                | 指定された `id` の webhook が存在しない（または並行リクエストで削除済み）           | `id` を確認；削除直後であれば webhook 一覧を再取得してから判断        |
| 500   | `Internal server error`                            | サーバ側の予期しない障害                                           | 指数バックオフでリトライ（5s 開始、最大 3 回）                    |