Webhookでミーティングデータをエクスポートする
Webhook連携を使ってミーティングデータをエクスポートし、カスタム連携を構築します
CirclebackのWebhookは、条件に一致するミーティングが終わるたびに、指定した公開HTTPS URLへJSON本文付きのPOSTリクエストを送信します。各リクエストには、HMAC-SHA256ダイジェストを含むX-Signatureヘッダーで署名が付けられているため、Circlebackから送信されたものであることを検証できます。Webhookを使って、ミーティングデータをエクスポートしたり、カスタム連携を構築したりできます。
設定
- 自動化を開き、新しい自動化を選択します。
- 自動化を実行するミーティングを絞り込む自動化の条件を追加し、次へを選択します。
- Webhookリクエストを送信を選択します。
- Webhookリクエストの送信先となるエンドポイントURLと、含めたいミーティングの成果物を入力します。
- 必要に応じて、最新のミーティングでテストリクエストを送信し、正しく動作することを確認します。
- 完了を選択します。
- 上部で自動化に名前を付け、保存を選択します。
これで、自動化の条件に一致するすべてのミーティングがWebhookエンドポイントに送信されます。
過去のミーティングをエクスポートするには、すべてのミーティングを選択し、アクションメニューから新しい自動化を選択します。
リクエスト
設定が完了すると、指定したエンドポイント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のアクションアイテムIDtitle(文字列):アクションアイテムのタイトルdescription(文字列):アクションアイテムの説明assignee(オブジェクトまたはnull):アクションアイテムの担当者オブジェクト。担当者が未割り当ての場合はnullname(文字列または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イベントの暗号署名を生成するために使用される、一意で安全な文字列です。
署名を検証するには、次の手順に従います。
- 受信リクエストのヘッダーから署名を取り出します。署名は
x-signatureという名前のヘッダーに含まれています。 - 署名シークレットとリクエスト本文を使って、期待される署名を生成します。
- 期待される署名と、提供された署名を比較します。一致すればリクエストは有効とみなされ、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を使って重複をスキップしてください。