> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/jp/webhook/ibentono.md).

# イベントの受信

## **イベント処理の全体フロー**

1. イベントが発生（トリガー）すると、GGWP の webhook がターゲットURLにペイロード（POSTリクエスト）を送信します。
   1. v1.0 : 送信されるペイロードはJSON文字列形式で、キーと値のペアの間に空白が入る場合があります。 `Content-Type`  ヘッダーは次のように設定されます `application/json` .
   2. v1.1 : 送信されるペイロードはJSON文字列形式で、空白はありません。これにより、HMAC検証のためにペイロードから空白を取り除く追加手順が不要になります。 `Content-Type`  ヘッダーは次のように設定されます `application/octet-stream` .
2. HMAC により受信リクエストを検証します。さらに、サーバーは認証のために（サブスクリプション作成時に設定される）カスタムヘッダーを利用できます。
3. ペイロードがターゲットURLに受信されると、ターゲットは次のものを返す必要があります **200 ステータスコード** ペイロードの受信が成功したことを示します。
4. 1分以内に200ステータスコードが返されない場合、試行は失敗とみなされます。その後3回再試行し、それでも失敗した場合は最終的にそのイベントに対するURL呼び出しを断念します。 

サブスクリプションイベントを受信するには、GGWP Webhooks から送信されるペイロードを受け取れるAPIを顧客が作成する必要があります。

## ターゲットURLの作成

任意のイベントトリガー時に、GGWP はターゲットURLを呼び出すことで情報を配信します。ターゲットURLは、次をサポートすることでこのようなイベントを処理することが期待されます `POST` API上のメソッド

## リクエストの検証

ターゲットURLに届くすべての受信リクエストは、それがGGWPから来たものであることを保証するために検証する必要があります。これはデジタル署名を計算することで行えます。各 webhook リクエストには base64 エンコードされた `x-ggwp-hmac-sha256` ヘッダーが含まれており、これはサブスクリプションの秘密鍵とリクエスト内で送信されたデータを使って生成されます。

{% hint style="warning" %}
v1.0 の実装では、正確な署名検証を確実にするため、HMACダイジェストを計算する前にペイロードデータからすべての空白を削除する必要があります。これは、整形や送信の過程で余分な空白文字が入り込む可能性があり、それらは実際の内容には影響しないものの、考慮しないと署名の不一致を招く可能性があるためです。
{% endhint %}

検証するには、次のアルゴリズムに従って HMAC ダイジェストを計算し、HMAC ダイジェストとヘッダー値が一致すれば、その webhook イベントは GGWP から送信されたものです。

{% code lineNumbers="true" fullWidth="false" %}

```python
# Python の例

import base64
import hashlib
import hmac
import json


# webhook サブスクリプション作成時に受け取る秘密鍵
SECRET_KEY = 'my_secret_key'

def verify_webhook(payload, hmac_header):
    digest = hmac.new(
        SECRET_KEY.encode('utf-8'), 
        json.dumps(payload, separators=(',', ':')).encode("utf-8"),
        digestmod=hashlib.sha256
    ).digest()
    computed_hmac = base64.b64encode(digest)

    return hmac.compare_digest(computed_hmac, hmac_header.encode('utf-8'))

```

{% endcode %}

> GoLang ベースのサーバーでは、1.0 の hmac 検証は動作しないため、Version 1.1 のみを使用することを推奨します。HMAC の計算は常に圧縮された JSON（空白なし）で行われます。

{% code lineNumbers="true" %}

```go
// Go の例

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"fmt"
)

// webhook サブスクリプション作成時に受け取る秘密鍵
const SECRET_KEY = "my_secret_key"

func verifyWebhook(payload string, hmacHeader string) bool {
	mac := hmac.New(sha256.New, []byte(SECRET_KEY))
	mac.Write([]byte(payload))
	digest := mac.Sum(nil)
	computedHmac := base64.StdEncoding.EncodeToString(digest)
	return hmac.Equal([]byte(computedHmac), []byte(hmacHeader))
}

```

{% endcode %}