# Webhookでミーティングデータをエクスポートする (/docs/ja/support/automations/export-meeting-data-with-webhooks)

CirclebackのWebhookは、条件に一致するミーティングが終わるたびに、指定した公開HTTPS URLへJSON本文付きのPOSTリクエストを送信します。各リクエストには、HMAC-SHA256ダイジェストを含む`X-Signature`ヘッダーで署名が付けられているため、Circlebackから送信されたものであることを検証できます。Webhookを使って、ミーティングデータをエクスポートしたり、カスタム連携を構築したりできます。

## 設定

1. 自動化を開き、**新しい自動化**を選択します。
2. 自動化を実行するミーティングを絞り込む自動化の条件を追加し、**次へ**を選択します。
3. **Webhookリクエストを送信**を選択します。
4. Webhookリクエストの送信先となるエンドポイントURLと、含めたいミーティングの成果物を入力します。
5. 必要に応じて、最新のミーティングでテストリクエストを送信し、正しく動作することを確認します。
6. 完了を選択します。
7. 上部で自動化に名前を付け、**保存**を選択します。

これで、自動化の条件に一致するすべてのミーティングがWebhookエンドポイントに送信されます。

過去のミーティングをエクスポートするには、[すべてのミーティングを選択](/docs/support/meetings/select-and-take-action-on-multiple-meetings)し、アクションメニューから新しい自動化を選択します。

## リクエスト

設定が完了すると、指定したエンドポイントURLで、次のフィールドを含むJSON本文付きのPOSTリクエストを受信するようになります。

- `id`（文字列）：CirclebackのミーティングID。Circleback上のミーティングへのリンクの生成に使用できます（`https://circleback.ai/meetings/${id}`）
- `name`（文字列）：ミーティング名
- `createdAt`（文字列）：ISO文字列形式のミーティング作成日
- `duration`（数値）：ミーティングの長さ（秒）
- `url`（文字列またはnull）：オンラインミーティングのURL（Zoom、Google Meet、Microsoft Teamsなど）
- `recordingUrl`（文字列またはnull）：ミーティングの録音ファイルのURL。24時間のみ有効です（設定でミーティングの録音の保存が有効になっている場合のみ利用できます）
- `tags`（文字列の配列）：ミーティングに追加されたタグの名前
- `icalUid`（文字列またはnull）：ミーティングに関連付けられたカレンダーイベントの一意の識別子
- `attendees`（オブジェクトの配列）：ミーティングの参加者
  - `name`（文字列またはnull）：カレンダーイベントに関連付けられている場合はカレンダーイベントの招待者名、それ以外の場合はミーティング参加者の名前
  - `email`（文字列またはnull）：カレンダーイベントに関連付けられている場合はカレンダーイベントの招待者のメールアドレス
- `notes`（文字列）：Markdown形式のCirclebackのミーティングノート
- `actionItems`（オブジェクトの配列）：ミーティングで作成されたアクションアイテムの配列
  - `id`（数値）：CirclebackのアクションアイテムID
  - `title`（文字列）：アクションアイテムのタイトル
  - `description`（文字列）：アクションアイテムの説明
  - `assignee`（オブジェクトまたはnull）：アクションアイテムの担当者オブジェクト。担当者が未割り当ての場合はnull
    - `name`（文字列またはnull）：担当者名
    - `email`（文字列またはnull）：担当者のメールアドレス
  - `status`（文字列）：アクションアイテムのステータス。'PENDING'または'DONE'のいずれか
- `transcript`（オブジェクトの配列）：ミーティングの文字起こしのセグメント
  - `speaker`（文字列）：話者名
  - `text`（文字列）：発言内容
  - `timestamp`（数値）：セグメントの開始を示すタイムスタンプ（秒）
- `insights`（オブジェクト）：
  - `[insightName]`（文字列のオブジェクトキー）：ユーザーが作成したインサイトの名前
    - オブジェクトの配列
      - `insight`（文字列。インサイトにカスタムフィールドがある場合はオブジェクト）：インサイトの結果
      - `speaker`（文字列またはnull）：インサイトに関連付けられた話者（該当する場合）
      - `timestamp`（数値またはnull）：インサイトに関連付けられたタイムスタンプ（秒）（該当する場合）

### 例

```
{
  "id": "WRweb12iCBimU6Vo8cD7z",
  "name": "Event Venue Review",
  "createdAt": "2023-07-25T20:30:57.926Z",
  "duration": 1306.09,
  "url": "https://meet.google.com/abc-defgh-xyz",
  "recordingUrl": null,
  "tags": ["Events"],
  "icalUid": "1a2b3c@google.com",
  "attendees": [
    { "name": "John Appleseed", "email": "john@example.com" },
    { "name": "Samantha Grey", "email": "sam@example.com" }
  ],
  "notes": "#### Overview\n*   Several options for event venues were reviewed...",
  "actionItems": [
    {
      "id": 252,
      "title": "Contact event venues",
      "description": "Reach out to Sunriver Events and other potential event venues to see if they would be open to hosting the event this summer.",
      "assignee": {
      	"name": "John Appleseed",
      	"email": "john@example.com"
      },
      "status": "PENDING"
    },
    {
      "id": 253,
      "title": "Review and finalize venue options",
      "description": "Review pricing and availability of venues and pick a venue for the event.",
      "assignee": null,
      "status": "PENDING"
    }
  ],
  "transcript": [
    {
	    "speaker": "John Appleseed",
	    "text": "Hey, how's it going?",
	    "timestamp": 4.56
    },
    {
	    "speaker": "Samantha Grey",
	    "text": "Going well, just testing webhooks in Circleback.",
	    "timestamp": 18.32
    }
  ],
  "insights": {
    "Customer details": [
	    {
		    "insight": {
			    "Company name": "Initech",
			    "Number of employees": 120
		    },
		    "speaker": "John Appleseed",
		    "timestamp": 800
	    }
    ],
    "Questions": [
			{
				"insight": "Is this thing on?",
				"speaker": "Samantha Grey",
				"timestamp": 49.15
			},
			{
				"insight": "When will the webhook integration be ready?",
				"speaker": "John Appleseed",
				"timestamp": 120.12
			}
    ]
  }
}
```

### 受信リクエストの検証（任意）

受信したWebhookイベントがCirclebackから送信されたものであることを確認するために、署名シークレットを使って受信リクエストを検証できます。この手順は任意ですが、セキュリティを高めるために推奨されます。

自動化でWebhookを設定すると、署名シークレットが発行されます。この署名シークレットは、各Webhookイベントの暗号署名を生成するために使用される、一意で安全な文字列です。

署名を検証するには、次の手順に従います。

1. 受信リクエストのヘッダーから署名を取り出します。署名は`x-signature`という名前のヘッダーに含まれています。
2. 署名シークレットとリクエスト本文を使って、期待される署名を生成します。
3. 期待される署名と、提供された署名を比較します。一致すればリクエストは有効とみなされ、Webhookイベントの処理に進めます。

TypeScriptでの実装例は次のとおりです。

```
import { createHmac, timingSafeEqual } from 'crypto'
import express from 'express'

// Mount this on the webhook route so req.body stays the raw bytes.
// Do not use express.json() before verifying.
export const rawJsonBody = express.raw({ type: 'application/json' })

export const verifyWebhookSignature = (
  requestBody: Buffer,
  signature: string,
  signingSecret: string
) => {
  const expectedSignature = createHmac('sha256', signingSecret)
    .update(requestBody)
    .digest('hex')

  const expected = Buffer.from(expectedSignature)
  const provided = Buffer.from(signature)

  return (
    expected.length === provided.length &&
    timingSafeEqual(expected, provided)
  )
}

export const webhookEndpointHandler = async (
  req: express.Request,
  res: express.Response
) => {
  try {
    const requestBody = req.body
    const signature = req.headers['x-signature']
    const signingSecret = 'your-signing-secret'

    if (
      !Buffer.isBuffer(requestBody) ||
      typeof signature !== 'string' ||
      !verifyWebhookSignature(requestBody, signature, signingSecret)
    ) {
      return res.status(401).json({ error: 'Invalid signature.' })
    }

    const payload = JSON.parse(requestBody.toString('utf8'))
    await processWebhookEvent(payload)

    return res.status(200).json({
      message: 'Webhook event processed successfully.',
    })
  } catch (error) {
    console.error('Error processing webhook event.', error)
    return res.status(500).json({ error: 'Error processing webhook event.' })
  }
}

app.post('/webhook', rawJsonBody, webhookEndpointHandler)
```

`'your-signing-secret'`は、Webhookの自動化ステップで発行された実際の署名シークレットに置き換えてください。

署名を検証することで、受信するWebhookイベントがCirclebackから送信されたもので、改ざんされていないことを確認できます。これにより、不正アクセスや潜在的な攻撃からアプリケーションを保護できます。

## 再試行

エンドポイントが2xx以外のレスポンスを返した場合、エラーが発生した場合、または5分以内に応答しなかった場合、Circlebackはリクエストを自動的に最大9回まで再試行します。再試行により同じミーティングが複数回届くことがあるため、ミーティングの`id`を使って重複をスキップしてください。