のために: 管理者
ウェブフックイベントとペイロードを調べてください
10個のフィードイベントそれぞれが何を送信するのか、メッセージがどのように暗号化されるのか、そして秘密鍵を使ってそれを復号化する方法について説明します。
この記事では4 セクション
このページには、ウェブハックWebhook フィードの投稿やコメントが変更されるたびに、ハブがあなたのシステムにメッセージを送信できるように、ハブに指定するアドレスです。が送信するイベントの一覧、各メッセージがどのようにして到着するか、そして復号化された後でメッセージに含まれる情報が何であるかが記載されています。
イベント
| イベント | 画面上で | 送信時 | contentは保持する |
|---|---|---|---|
add_post | 投稿が作成されました。 | 誰かが、その事件の「フィード」に投稿をするのです。 | new:投稿のテキスト |
modify_post | 投稿内容が変更されました。 | 投稿されたテキストが変更されました。 | new:新しいテキスト |
delete_post | その投稿は削除されました。 | その投稿は削除されました。 | old:そのテキスト |
add_post_comment | コメントの投稿が行われました。 | 誰かが投稿にコメントを残しました。 | new:コメントのテキスト |
modify_post_comment | コメントの内容が変更されました。 | コメントのテキストが変更されました。 | new:新しいテキスト |
delete_post_comment | コメントは削除されました。 | コメントが削除されました。 | old:そのテキスト |
add_post_media | ポストメディアが作成されます。 | ファイルが投稿に追加されました。 | new:そのファイルへのリンクです。 |
delete_post_media | そのメディア投稿は削除されました。 | ファイルが投稿から削除されました。 | old:削除されたファイルへのリンクです。 |
add_post_comment_media | コメントを投稿できるメディアが作成されました。 | ファイルがコメントに追加されました。 | new:そのファイルへのリンクです。 |
delete_post_comment_media | コメントを投稿したメディアが削除されました。 | ファイルがコメントから削除されました。 | old:削除されたファイルへのリンクです。 |
- あなたのハブにあるすべてのケースには、変更を加えた人が送信する情報が含まれています。その人は、スタッフであれ、クライアントであれ、バーチャルアシスタントバーチャルアシスタント 会社への歓迎メッセージ、チェックイン、ステージングに関する投稿を行う自動化されたチームメンバー。その投稿にはバーチャルアシスタントのバッジが付いています。であれ、インポートされたデータやAPIキーであれです。投稿やコメントのイベントについては、その投稿者がケースを離れてからも、依然として記録されます。
- ケースを削除すると、何も送信されません。削除される投稿については、
delete_postというものも送信されません。一度削除されると、APIはそのケースに対して404エラーを返します。 - 投稿や投稿に関するコメントだけが、イベントを発生させることができます。ノート、タスク、フォーム、電子署名、そしてそれらに関するコメントは、何も発生させません。また、誰がその投稿を見ることができるかを変更しても、何も変化しません。
- ファイルを含む投稿の場合、
add_postが送信され、その後、各ファイルにつき1つのadd_post_mediaが送信されます。 - ファイルリンクは、48時間だけ有効です。削除されたファイルは、その後すぐに破棄されるため、削除イベントで設定されたリンクは、実際には開けないかもしれません。
- 文中で言及されている場合、その人のユーザーIDは
<@となります。また、その人の情報としては>が含まれています。例えば、<@cu-4f1c2a9e8b7d60>のようなものです。
配達
- 各メッセージは、ウェブホックのアドレスにPOSTされるものです。メッセージのボディには、
payloadというフィールドが含まれており、その値が暗号化されたメッセージです。 - 10秒以内に400未満のステータスになった場合、それは配達されたとみなされます。
- 送信が失敗した場合、そのメッセージは再送されません。2回連続でウェブホックが停止した場合は、ウェブホックの送信が停止している問題を解決してくださいを参照してください。
- メッセージは、二度届くこともありますし、順序が崩れることもあります。その場合は、イベントやアイテムのID、そして
whenを使って、その状況を伝える必要があります。
{"payload": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ.…"}
復号化
payloadは、コンパクト形式のJWEであり、RSA-OAEPおよびA128CBC-HS256を用いて暗号化されています。ウェブホックのシークレットとは、対応する秘密鍵のことです。これは、-----BEGIN PRIVATE KEY-----で始まるPEMファイルです。ダウンロードしたファイルを使用するか、または、行間を含めてコピーされたシークレットを使用してください。どのJOSEライブラリでも、このデータを復号できます。
Python、jwcryptoを使って
import json
from jwcrypto import jwk, jwt
with open("webhook-private-key.pem", "rb") as f:
key = jwk.JWK.from_pem(f.read())
def read_message(body):
token = jwt.JWT(jwt=body["payload"], key=key, expected_type="JWE")
return json.loads(token.claims)
Node.js、joseを使って
import { readFileSync } from 'node:fs';
import { compactDecrypt, importPKCS8 } from 'jose';
const key = await importPKCS8(readFileSync('webhook-private-key.pem', 'utf8'), 'RSA-OAEP');
export async function readMessage(body) {
const { plaintext } = await compactDecrypt(body.payload, key);
return JSON.parse(new TextDecoder().decode(plaintext));
}
別途の署名はありません。ユーザーのハブは、自分が暗号化した鍵を表示しません。そのため、自分の秘密鍵を使って復号化されたメッセージは、ユーザーのハブから送られてきたものです。しかし、途中で変更された鍵を使って復号化しようとすると、復号化が失敗します。もし複数のハブが同じアドレスにメッセージを送信した場合は、who.host.host_idも確認してください。
メッセージ
解密されたadd_post:
{
"who": {
"user_id": "cu-4f1c2a9e8b7d60",
"cc_owner": false,
"post": {"post_id": "post::20261001140322_9f8e7d6c5b4a32"},
"case": {"case_id": "cc-1a2b3c4d5e6f70", "case_ref_id": "rear-end-2026"},
"role": {"role_id": "role::staff"},
"host": {"host_id": "ca-7e6d5c4b3a2f10"}
},
"what": {
"trigger": {"name": "add_post"},
"content": {
"new": "Hi Jane, your records request went out today.",
"type": "app_add_post",
"kwargs": {"case_id": "cc-1a2b3c4d5e6f70", "case_ref_id": "rear-end-2026"}
}
},
"where": {"location": {"name": "app"}, "module": {"name": "post"}},
"when": {"datetime": {"timezone": "utc", "datetime": "2026-10-01T14:03:22.123456+0000"}},
"targets": {"user_ids": ["cu-4f1c2a9e8b7d60"], "cc_user_ids": [], "group_targets": false}
}
| 分野 | 中身 |
|---|---|
what.trigger.name | 上の表から得られるこのイベントについて |
what.content.new または what.content.old | テキスト、またはそのファイルへのリンク |
who.user_id | その投稿やコメントを書いたのは誰なのか、また、他の人がそれを変更したり削除したりした場合はどうなるのか。 |
who.post.post_id | その投稿は、出来事に関するものでした。 |
who.comment.comment_id | コメントに関する、そのコメントの出来事についての情報です。 |
who.comment.post_id | コメントが投稿されている場所 |
who.case.case_id | このケースは、APIが使用するIDによって分類されています。 |
who.case.case_ref_id | このケースのタグIDタグID ケースに付ける永続的なラベル。例えば、rear-end-2026 など。参照 ID としても表示され、インポート時に使用されます。 |
who.role.role_id | 著者がそのケースに関与しているかどうかを示すものです。例えば、role::clientsのような形式です。もし著者がそのケースから離れていれば、この値は欠落します。 |
who.host.host_id | あなたのパートナー |
when.datetime.datetime | そのことが起こった時は、UTCでした。 |
他のフィールドは、ハブ自身の使用のためのものです。無視してください。