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

# Webhooks

> WhatsAppイベントを署名されたHTTP POSTリクエストとして受信します: 設定、イベントの種類、ペイロード形式、署名、再試行。

GOWA は、メッセージ、レシート、受信するすべてのWhatsAppイベントのURLにJSONドキュメントを投稿します。 リアクション、編集、削除、インジケータ入力、グループ変更、ラベル、ニュースレターや通話。

Webhook登録エンドポイントがありません。起動時またはデバイスごとに、`/devices/{device_id}/webhook` を使用してWebhookを設定します。

## 配送方法

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant WA as WhatsApp
    participant G as GOWA
    participant R as Your receiver
    WA->>G: Event (whatsmeow)
    G->>G: Skip if chat/sender matches WHATSAPP_WEBHOOK_IGNORE_JIDS
    G->>G: Resolve targets (per-device webhook or global WHATSAPP_WEBHOOK)
    G->>G: Skip target if event not in its allowlist (WHATSAPP_WEBHOOK_EVENTS)
    loop Up to 5 attempts, 10 s timeout each
        G->>R: POST JSON {event, device_id, session_id, payload}<br/>X-Hub-Signature-256: sha256=HMAC(body, secret)
        R->>R: Verify HMAC over raw body
        alt 2xx
            R-->>G: 200 OK (delivered, stop)
        else non-2xx or network error
            R-->>G: Error
            G->>G: Wait 1 s, 2 s, 4 s, then 8 s before the next attempt
        end
    end
    Note over G: After the 5th failure the event is logged and dropped
```

各ターゲット URL はそれぞれ個別にシークレットとリトライで配信されます。

## 設定

```bash theme={null}
# one or more URLs, comma-separated
WHATSAPP_WEBHOOK=https://example.com/wa-hook,https://backup.example.com/wa-hook
WHATSAPP_WEBHOOK_SECRET=replace-with-a-private-key # stable HMAC key
WHATSAPP_WEBHOOK_EVENTS=message,message.ack # optional allowlist; empty = all events
WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us          # optional; skip chats or senders
WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=false # verify HTTPS certificates
WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=false  # optional linked-device receipts
```

同等のフラグ: `--webhook`, `--webhook-secret`, `--webhook-events`, `--webhook-ignore-jids`, `--webhook-insecure-skip-verify`, and `--webhook-all-device-receipts`

明示的に秘密の署名キーを設定します。 未設定のキーまたは古い公開された値 `secret` を使用すると、GOWA は再起動時に変更され警告を記録するランダムなキーを生成します。 受信者は再起動時に署名を検証するために明示的な共有鍵を必要とします。HTTPS 証明書はデフォルトで検証されます。

## イベント

| イベント | 発火したとき |
| - | - |
| `message` | メッセージ（テキスト、メディア、連絡先、場所、ポーリングなど）が届きます。`is_from_me`は、このアカウントから送信されたメッセージに対して`true`です。 |
| `message.reaction` | 誰かがメッセージに反応します。 |
| `message.revoked` | 全員にメッセージが削除されます。 |
| `message.edited` | メッセージが編集されました。 |
| `message.ack` | レシート（`receipt_type`：`delivered`、`read`、...） |
| `message.deleted` | メッセージが削除されます。 |
| `chat_presence` | 連絡先が開始または入力または記録を停止します。 |
| `presence` | 登録された連絡先はオンラインまたはオフラインになります。プレゼンス契約と利用可能なクライアントが必要です。 |
| `group.participants` | メンバーが参加、退会、降格(`type`: `join`, `leave`, `promote`, `demote`)を行います。 |
| `group.info` | グループ名が変更されます。Payload には、新しい `name` と `name_set_by` が含まれます。 |
| `group.joined` | アカウントがグループに追加されました。 |
| `label.edit` | WhatsAppビジネスラベルが作成または変更されます。 |
| `label.association` | チャットにラベルが適用または削除されます。 |
| `newsletter.joined` / `newsletter.left` | あなたはチャンネルをフォローまたはアンフォローします。 |
| `newsletter.message` | 購読しているチャンネル投稿のライブビュー、転送、リアクションカウンターの更新。 |
| `newsletter.mute` | チャンネルのミュート設定が変更されます。 |
| `call.offer` | 着信。`WHATSAPP_AUTO_REJECT_CALL=true` では自動的に拒否されます。 |
| `device.logged_out` | WhatsAppは、その理由コードを含むデバイスをログアウトします。 |
| `device.temporary_ban` | WhatsAppは一時的にアカウントを禁止します。 |
| `device.reachout_timelock` | WhatsAppは、新しいチャットの開始の制限を有効化またはリフトします。 |

許容リストのイベント名は大文字と小文字を区別しません。

## 積載量

すべてのリクエストには同じエンベロープがあります:

```json theme={null}
{
  "event": "message",
  "device_id": "628123456789@s.whatsapp.net",
  "session_id": "sales",
  "payload": {
    "id": "3EB0C127D7BACC83D6A1",
    "chat_id": "628987654321@s.whatsapp.net",
    "from": "628987654321@s.whatsapp.net",
    "from_lid": "251556368777322@lid",
    "from_name": "John Doe",
    "sender_display_name": "John Doe",
    "timestamp": "2026-10-15T10:30:00Z",
    "is_from_me": false,
    "body": "Hello, how are you?"
  }
}
```

| フィールド | 説明 |
| - | - |
| `event` | 上記のイベント名の一つ。 |
| `device_id` | イベントを受信したアカウントのJID。スロットにまだJIDがない場合、デバイスイベントは省略されます。 |
| `session_id` | `POST /devices`からのIDなどのスロット ID。自動的に作成されたスロットはWhatsApp JIDを使用することがあります。 デバイスイベントには常にそれが含まれています。JIDがスロットにマッピングできない場合、他のイベントは省略される可能性があります。 |
| `payload` | イベント固有のデータ。一般的なフィールド：`id`、`chat_id`、`from_lid`、`from`、`from_name`、`sender_display_name`、`timestamp`（RFC 3339）、`is_from_me`。 |

返信は `replied_to_id` と `quoted_body` を追加します。レシートは `ids` (配列) と `receipt_type` を使用します。 グループ参加イベントは `chat_id` 、 `type` 、 `jids` を持ちます。グループ名の変更は別の `group.info` 形式を使用します。

`sender_display_name` は `from` が空でない文字列の場合にのみ表示されます。 別の送信者の場合は、保存された連絡先名、ライブイベントのプッシュ名、保存されたプッシュ名、ビジネス名、JIDユーザーの方をお選びいただけます。 アクティブなアカウントでは、アカウントのプッシュ名、JID IDを好みます。 解決策は最善の努力です。従来の `from_name` はメッセージイベントのプッシュ名のままです。

WhatsAppが認証された名前証明書を提供する場合、受信メッセージには`is_business: true`、`verified_name`、および `verified_level`を含めることができます。これらのフィールドはそれ以外の場合は省略されます。 送信者がビジネスであるかどうかは不在であり、公式バッジの保証ではなく、 `verified_level` は生の上流の値です。

### メディア

`WHATSAPP_AUTO_DOWNLOAD_MEDIA=true`（デフォルト）では、メディアは`statics/media/`に保存され、メディアフィールドはパスを保持します。

```json theme={null}
{
  "image": "statics/media/1752404751-ad9e37ac-c658-4fe5-8d25-ba4a3f4d58fd.jpeg"
}
```

キャプションがある場合、フィールドは `{"path": "...", "caption": "..."}` となり、キャプションは `body` にも含まれます。自動ダウンロードが無効の場合は `{"url": "https://mmg.whatsapp.net/...", "caption": "..."}` となります。後から `GET /message/{message_id}/download?phone=<chat>` でファイルを取得してください。

ペイロードの全一覧（投票、位置情報、連絡先、一度だけ表示、広告経由の参照情報など）は、アップストリームの [Webhook ペイロードリファレンス](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/webhook-payload.md)を参照してください。

## アルバムと構造化メッセージ

複数の `message` イベントとしてアルバムが届きます。ヘッダーにはメッセージ本文がなく、期待されるアイテム数が含まれています。

```json theme={null}
{
  "id": "ALBUM_HEADER_ID",
  "album": {
    "expected_image_count": 3,
    "expected_video_count": 1
  }
}
```

それぞれの写真やビデオは `album_id: "ALBUM_HEADER_ID"` で通常のメディア・イベントに届きます。 そのIDでグループ項目。ヘッダーはダウンロード可能なメディア項目ではなく、Chatwootに転送されません。

投票の作成、投票、編集、追加オプションは `message` を使用します。`body` に頼るのではなく、構造化された `poll` オブジェクトを調査します。 オプションハッシュは、正確なオプション名の小文字の16進SHA-256ハッシュです。既存の`WHATSAPP_WEBHOOK_EVENTS=message`サブスクリプションはこれらの相互作用を受け取ります。

## オンラインとオフラインの存在

イベントを受信する同じデバイスを使用して、個々の連絡先ごとに購読する:

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/user/presence/subscribe \
  -H "X-Device-Id: sales" \
  -H "Content-Type: application/json" \
  -d '{"phone":"628987654321"}'
```

成功したレスポンスには `results.subscribed: true` と `results.jid` が含まれています。グループとニュースレターの JID は拒否されます。 サブスクリプションは、デバイスのプレゼンス設定を上書きしません。継続的なアップデートの場合は、以下のようにGOWAを開始してください。

```bash theme={null}
WHATSAPP_PRESENCE_ON_CONNECT=available
WHATSAPP_PRESENCE_PULSE_ENABLED=false
WHATSAPP_WEBHOOK_EVENTS=message,presence
```

デフォルトのプレゼンスパルスは、デバイスが利用できない状態にマークすることで終了し、連絡先のプレゼンスの更新が停止します。 利用可能なデバイスをマークすると、それが実行中のWhatsAppプッシュ通知を抑制します. 連続トラッキングを有効にする前に、このトレードオフのためのアカウント.

```json theme={null}
{
  "event": "presence",
  "device_id": "628123456789@s.whatsapp.net",
  "timestamp": "2026-10-29T12:05:00Z",
  "payload": {
    "from": "628987654321@s.whatsapp.net",
    "state": "unavailable",
    "last_seen": "2026-10-29T12:04:35Z"
  }
}
```

`state` は `available` または `unavailable` です。`last_seen` は、連絡先のプライバシー設定で不明または非表示になった場合は省略されます。 `from_lid`は該当する場合に含まれます。入力と記録は別個の`chat_presence`イベントのままで、このサブスクリプションは使用しません。

## グループ名の変更

```json theme={null}
{
  "event": "group.info",
  "device_id": "628123456789@s.whatsapp.net",
  "timestamp": "2026-10-29T10:35:00Z",
  "payload": {
    "chat_id": "120363402106000000@g.us",
    "name": "Project team",
    "name_set_by": "628987654321@s.whatsapp.net"
  }
}
```

`name_set_by`は、可能な場合はLIDから電話JIDに解決され、WhatsAppが俳優を特定しない場合は省略されます。 イベントが他のイベントを除外する場合は、明示的に `group.info` を購読します。

## ニュースレターカウンターの更新

`newsletter.message` は新しい投稿の本文ではなくライブカウンターを報告します。エントリーには常に`server_id`が含まれます。 `message_id`、`type`、`timestamp`はWhatsAppが提供していない場合は省略されます。ゼロまたは欠席カウンターは省略できます。

```json theme={null}
{
  "event": "newsletter.message",
  "device_id": "628123456789@s.whatsapp.net",
  "timestamp": "2026-10-29T12:00:00Z",
  "payload": {
    "newsletter_id": "120363000000000000@newsletter",
    "messages": [
      {"server_id": 42, "views_count": 120, "forwards_count": 3}
    ]
  }
}
```

利用可能な場合、`reaction_counts`にはWhatsAppのリアクションカウントが含まれます。 ニュースレターIDとサーバーIDで更新を消費します。欠落しているカウンターをゼロにリセットしないでください。

## アカウントの制限とログアウト

デバイスイベントは常に `session_id` を持ち、同じWhatsApp番号を使用するスロットは区別可能です。このイベントでは発光スロットのWebフック設定を使用します。 リモートログアウトは、再ペアリングのためのスロットを保持し、ログアウト前からIDを報告します。 スロットのWebhook設定は再ペアリングのまま残ります。これらのイベントはChatwootには送信されません。

```json theme={null}
{
  "event": "device.logged_out",
  "device_id": "628123456789@s.whatsapp.net",
  "session_id": "sales",
  "timestamp": "2026-10-29T09:00:00Z",
  "payload": {
    "code": 401,
    "reason": "logged out from another device",
    "on_connect": true
  }
}
```

| イベント | ペイロードフィールド |
| - | - |
| `device.logged_out` | `code`、`reason`、`on_connect`。`on_connect` は、接続が拒否された場合と、確立済みの接続が切断された場合を区別します。 |
| `device.temporary_ban` | `code`, `reason`, `expires_in_seconds` .`expires_at`は計算されたRFC 3339の有効期限で、継続時間が正の場合にのみ表示されます。セッションは保持されます。 |
| `device.reachout_timelock` | `is_active`。オプションの `enforcement_type` はWhatsAppの値を渡します。オプションの `ends_at` は RFC 3339 の有効期限です。`is_active: false` は、WhatsAppが制限を解除したことを意味します。 |

コードは変更されずに転送され、理由のテキストは whatsmeow から来ています。未知のコードはまだ届いています。 `403`と`406`だけでログアウトコードは正確な原因を確立しません。 一時的な禁止期間は、WhatsAppが期限切れを与えなかったことを意味します。リーチアウトタイムロックは新しいチャットを開始し、送信エラー463を発生させる可能性があります。

## 署名の確認

それぞれのリクエストには `X-Hub-Signature-256: sha256=<hex>`、webhookシークレット付きの**raw** リクエストボディの HMAC-SHA256 が含まれます。 JSON を解析する前に、受信した正確なバイト数を計算します。

```javascript Node.js (Express) theme={null}
const express = require("express");
const crypto = require("crypto");
const app = express();
const SECRET = process.env.WEBHOOK_SECRET;

app.post("/wa-hook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const signature = req.get("X-Hub-Signature-256") || "";
  if (!/^sha256=[0-9a-f]{64}$/.test(signature)) return res.sendStatus(401);
  const received = signature.slice(7);
  if (received.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
    return res.sendStatus(401);
  }
  const evt = JSON.parse(req.body);
  res.sendStatus(200);            // acknowledge fast
  handle(evt);                    // then process
});
```

```python Python (Flask) theme={null}
import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["WEBHOOK_SECRET"].encode()

@app.post("/wa-hook")
def wa_hook():
    raw = request.get_data()
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Hub-Signature-256", "").removeprefix("sha256=")
    if not hmac.compare_digest(expected, received):
        abort(401)
    evt = request.get_json()
    # enqueue evt for processing
    return "", 200
```

```go Go theme={null}
func waHook(w http.ResponseWriter, r *http.Request) {
	raw, _ := io.ReadAll(r.Body)
	mac := hmac.New(sha256.New, []byte(os.Getenv("WEBHOOK_SECRET")))
	mac.Write(raw)
	expected := hex.EncodeToString(mac.Sum(nil))
	received := strings.TrimPrefix(r.Header.Get("X-Hub-Signature-256"), "sha256=")
	if !hmac.Equal([]byte(expected), []byte(received)) {
		http.Error(w, "bad signature", http.StatusUnauthorized)
		return
	}
	w.WriteHeader(http.StatusOK)
	// process raw asynchronously
}
```

## 配信と再試行

* それぞれの試みは**10秒**後に繰り返されます。
* 2xx以外の応答またはネットワークエラーは再試行されます。 GOWAは**5回の試行**を行い、1秒、2秒、4秒、8秒の試行を行います。 イベントハンドラーのコンテキスト期限は、すべての試行が完了する前に配信を停止することができます。
* 最後の失敗後、イベントは削除され、記録されます。永続的なキューまたはデッドレターストアはありません。
* いくつかのURLが独立して配信されます。

イベントをあなた自身の耐久性のある処理キューに受け入れた後、`2xx`に対応します。再試行されたイベントが複数回到着する可能性があるため、ハンドラを無防備にします。

## リンクされたデバイスの領収書を表示する

既定では、GOWAはプライマリデバイスからの連絡先確認を転送し、重複を軽減します。 すべてのデバイスから現在のアカウントの`read`と`read-self`レシートが渡されます。 これらの領収書については、`payload.from`はアカウントJIDで、`payload.ids`は読み込まれたメッセージを識別します。

連絡先の電話がオフラインの場合を含め、リンクされたデバイスから連絡先のレシートを受け取るには、`WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true` または `--webhook-all-device-receipts=true` を設定してください。 CLI フラグは明示的な `false` を含む環境を上書きします。

このオプトインは、重複またはオーダー外の確認を生成することができます。アカウント、チャット、およびメッセージ ID ごとに同期的に更新を適用します。 古いレシートが到着したときに配信される読み取りメッセージをダウングレードしないでください。メッセージIDと送信者JIDはデバイスのサフィックスなしで標準的なフォームを保持します。

## 予定をフィルター

**型順:** `WHATSAPP_WEBHOOK_EVENTS=message,message.ack` はこれらのイベントのみを転送します。

**チャットまたは送信者:** `WHATSAPP_WEBHOOK_IGNORE_JIDS`は`chat_id`、`from`、`chat_lid`、`from_lid`にマッチします。 `@`で始まるエントリは、アドレス空間全体(`@g.us`、`@s.whatsapp.net`、`@lid`)のワイルドカードです。

```bash theme={null}
# drop all group traffic plus one specific contact
WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us,628123456789@s.whatsapp.net
```

`@s.whatsapp.net` もグループメッセージと一致します。`from`はユーザーJIDです。グループをミュートするには`@g.us`を使用します。 2つのフィルタの組み合わせ: イベントは、そのタイプが許可されている場合にのみ送信され、そのJIDは無視されません。

## デバイス毎のWebhook数

スロットに独自のWebhook、シークレット、およびイベント許可リストを与えます:

```bash theme={null}
curl -u admin:changeme -X PATCH http://localhost:3000/devices/sales/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://sales.example.com/wa-hook",
    "webhook_secret": "sales-secret",
    "webhook_events": "message,message.ack",
    "webhook_insecure_skip_verify": false
  }'
```

同じフィールドは `POST /devices` で受け付けられています。`GET /devices/{device_id}/webhook` で現在の設定を読んでください。`"webhook_url": ""` でクリアしてください。

空のデバイス `webhook_secret` または `webhook_events` は対応するグローバル設定に戻ります。保存されているデバイス `webhook_insecure_skip_verify` ブール値はグローバル設定に置き換えられます。 特に、`false` は、グローバルバイパスが有効な場合でも証明書の検証が有効になります。

```mermaid theme={null}
flowchart TD
    A[Event for a device] --> B{Device has its own webhook_url?}
    B -- No --> G[Send to global WHATSAPP_WEBHOOK URLs<br/>global secret and allowlist]
    B -- Yes --> C{WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true?}
    C -- No --> D[Send to device URL only<br/>device secret and allowlist]
    C -- Yes --> E[Send to device URL and global URLs<br/>each with its own secret and allowlist<br/>duplicate URLs receive the event once]
```

デフォルトでは、デバイス毎のURLを**置き換え**、そのスロットにグローバルな`WHATSAPP_WEBHOOK`を置き換えます。 `WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true`では、代わりにグローバルURLに**追加**されます。デバイスURLはデバイスのシークレットと許可リストを使用します。 グローバルURLはグローバルURLを保持し、両方に存在するURLはイベントを一度受信します。 無視する JID ルールは両方に適用されます。

## ローカルテスト

ローカルの受信者をトンネル（例えば `ngrok http 8080`）で公開し、`WHATSAPP_WEBHOOK` をトンネル URL に設定します。 `--debug=true`では、GOWAは配達の試行と失敗ごとにログを記録します。

## イベントを受け取るその他の方法

* **[WebSocket](https://gowa-docs.mintlify.site/ja/api-reference/websocket.md)** at `/ws?device_id=<id>` は、ペアリングとステータスイベントをダッシュボードのクライアントにプッシュします。メッセージ配信にWebhookを使用します。
* **ポーリング:** `GET /chats` と `GET /chat/{chat_jid}/messages` はGOWAのローカルチャットストレージを読み込みます。[Receiving messages](https://gowa-docs.mintlify.site/ja/examples/receiving-messages.md)を参照してください。


## Related topics

- [Chatwoot webhook エンドポイント](https://gowa-docs.mintlify.site/ja/api-reference/chatwoot/chatwoot-webhook-エンドポイント.md)
- [デバイスの webhook 設定を設定します](https://gowa-docs.mintlify.site/ja/api-reference/device/デバイスの-webhook-設定を設定します.md)
- [デバイスの webhook 設定を取得します](https://gowa-docs.mintlify.site/ja/api-reference/device/デバイスの-webhook-設定を取得します.md)
- [デバイス毎のChatwoot Webhookエンドポイント](https://gowa-docs.mintlify.site/ja/api-reference/chatwoot/デバイス毎のchatwoot-webhookエンドポイント.md)
- [構成の参照](https://gowa-docs.mintlify.site/ja/configuration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.