Webhook
Webhook は、Crewcade があなたのサーバーに送るメッセージです。クラブで何かが変わったときに届きます。たとえば、メンバーがイベントに申し込んだとき、メンバーが参加したとき、イベントが変わったときです。何度も問い合わせる必要はありません。
メッセージには ID だけが入ります。名前やメールアドレスは入りません。詳しい内容は、メンバー、イベント、申し込みのエンドポイントで、あなたのサーバーが読み取ります。
エンドポイントを追加する
Section titled “エンドポイントを追加する”エンドポイントは、あなたのサーバーのウェブアドレスです。受け取りたいイベントも一緒に選びます。オーナーと管理者が追加できます。Webhook管理 権限を持つ役割の人も追加できます。
- 設定 を開き、開発者 を選びます。Webhook タブを開きます。
- エンドポイントの追加を押します。
- サーバーの
httpsアドレスを入力します。 - 受け取りたいイベントを選びます。必要なら説明を入れます。
- エンドポイントを保存します。
- シークレットをコピーします。シークレットは
whsec_で始まります。
シークレットが表示されるのは一度だけです。安全な場所に保管してください。サーバーは、このシークレットで各メッセージを確認します。
1 つのクラブに追加できるエンドポイントは 10 件までです。エンドポイントが追加されるたびに、クラブのオーナーにメールが届きます。
エンドポイントのアドレスのルールです。
httpsを使います。httpは使えません。- 公開インターネット上のアドレスを使います。プライベート、ローカル、内部のアドレスは使えません。
- Crewcade はリダイレクトをたどりません。最終的なアドレスを入力してください。
- アドレスにユーザー名やパスワードを入れないでください。
- アドレスは 2048 文字までです。
エンドポイントごとに、受け取るイベントを選びます。全部で 8 種類あります。
| イベント | 送られるとき |
|---|---|
registration.created | 申し込みが確定したとき。無料の申し込みはすぐに確定します。有料の申し込みは、支払いのあとに確定します。 |
registration.cancelled | 確定した申し込みが終わったとき。メンバーのキャンセル、ホストによる日程やイベントの中止、返金で終わります。 |
member.joined | 人がクラブに参加したとき。 |
member.updated | メンバーが変わったとき。プロフィール、写真、SNS リンク、クラブの項目、役割が対象です。停止と停止の解除、参加の承認、メンバーシップの枠の終了も対象です。 |
member.left | 管理者がメンバーを削除したとき。 |
event.created | イベントが公開されたとき。 |
event.updated | イベントが変わったとき。 |
event.cancelled | イベント全体、または 1 つの日程が中止されたとき。イベントの非公開や削除でも送られます。 |
下書きのメッセージは送られません。event.created の直後に event.updated が届くことがあります。
テスト送信 を押すと、webhook.test メッセージも送られます。このメッセージはイベントとして選べません。
エンドポイントを作った人が、次の権限を持っている必要があります。APIキーで作る場合は、キーと、キーを作った人の両方が持っている必要があります。
| イベント | 必要な権限 |
|---|---|
registration.created、registration.cancelled | すべてのイベントを表示 と 参加者チェックイン |
member.joined、member.updated、member.left | メンバー閲覧 |
event.created、event.updated、event.cancelled | すべてのイベントを表示 |
作った人が権限を失うと、その権限が必要なイベントの送信は止まります。member.updated で機微な項目だけが変わった場合は、作った人が機微なメンバー情報を見られるときだけ送られます。
メッセージはすべて JSON です。次の 4 つの項目があります。
{ "id": "msg_2Hq8rT5vK1mXc9LwP3sNdZa7", "type": "registration.created", "timestamp": "2026-11-12T01:30:00.000Z", "data": {}}| 項目 | 意味 |
|---|---|
id | メッセージの ID。webhook-id ヘッダーと同じです。 |
type | イベント名。 |
timestamp | Crewcade がメッセージを作った時刻。UTC の ISO-8601 形式。 |
data | 変わったものを指す ID。type によって変わります。 |
申し込みのイベント
Section titled “申し込みのイベント”{ "id": "msg_2Hq8rT5vK1mXc9LwP3sNdZa7", "type": "registration.created", "timestamp": "2026-11-12T01:30:00.000Z", "data": { "registrationId": "reg_123", "memberId": "mem_456", "seriesId": "ab12cd34", "occurrenceId": "k3m9x2pq", "source": null }}memberIdは、その人がメンバーシップを持っていないときnullです。seriesIdは、単発のイベントではnullです。sourceは、申し込みが変わった理由です。nullのこともあります。
メンバーのイベント
Section titled “メンバーのイベント”{ "id": "msg_9Bd4fGh2JkLm6NpQr8StVw1X", "type": "member.updated", "timestamp": "2026-11-12T02:00:00.000Z", "data": { "memberId": "mem_456", "source": null }}イベントのイベント
Section titled “イベントのイベント”{ "id": "msg_4Yc7ZaB1dEf3GhJ5KmN8PqRs", "type": "event.updated", "timestamp": "2026-11-12T03:00:00.000Z", "data": { "seriesId": "ab12cd34", "occurrenceId": "k3m9x2pq", "source": "details" }}source は、created、published、time_or_location、details、series_split、host、schedule_edit、unpublished、deleted のどれかです。
シリーズと日程
Section titled “シリーズと日程”繰り返しのイベントには、たくさんの日程があります。日程ごとに、8 文字の occurrenceId があります。これは GET /events が返す id と同じです。すべての日程は 1 つの seriesId を共有します。日程、シリーズ、IDを見てください。
シリーズ全体が変わったときは、occurrenceId が null です。すべての日程を読むには、その seriesId を付けて GET /events?seriesId= を呼びます。
詳しい内容を読む
Section titled “詳しい内容を読む”ID を使い、APIキーで現在の状態を読み取ります。
curl https://api.crewcade.com/api/v1/events/k3m9x2pq \ -H "Authorization: Bearer cck_your_key_here"署名を確認する
Section titled “署名を確認する”Crewcade は、すべてのメッセージに署名します。メッセージを信頼する前に、署名を確認してください。あなたのアドレスには、誰でもリクエストを送れます。シークレットを持っているのは Crewcade だけです。
Crewcade は Standard Webhooks のルールに従います。リクエストには 3 つのヘッダーがあります。
| ヘッダー | 意味 |
|---|---|
webhook-id | メッセージの ID。再送しても同じです。 |
webhook-timestamp | Crewcade がリクエストを送った時刻。1970 年からの秒数です。 |
webhook-signature | 署名。v1, のあとに base64 が続きます。署名が 2 つあるときは、スペースで区切ります。 |
メッセージを確認する手順です。
- リクエストの生の本文を読みます。解析して書き直さないでください。
webhook-id、webhook-timestamp、生の本文を、間にドットを入れてつなぎます。結果は${id}.${timestamp}.${rawBody}です。- そのテキストの HMAC-SHA256 を作ります。鍵は、シークレットの
whsec_のあとの部分を base64 から戻したものです。 - 結果を base64 にします。それぞれの
v1署名と比べます。 - タイムスタンプが 5 分より古いリクエストは拒否します。
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyWebhook(headers, rawBody, secret) { const id = headers['webhook-id']; const timestamp = headers['webhook-timestamp']; const signatures = String(headers['webhook-signature']).split(' ');
const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp)); if (!id || !timestamp || ageSeconds > 300) return false;
const key = Buffer.from(secret.replace('whsec_', ''), 'base64'); const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();
return signatures.some((signature) => { const [version, value] = signature.split(','); if (version !== 'v1' || !value) return false; const actual = Buffer.from(value, 'base64'); return actual.length === expected.length && timingSafeEqual(actual, expected); });}必ず生の本文を使ってください。フレームワークが本文を解析して書き直すと、元の文字列と変わることがあります。その場合、確認に失敗します。
公式ライブラリも使えます。standardwebhooks.com にあります。署名とタイムスタンプを代わりに確認してくれます。
配信と再試行
Section titled “配信と再試行”10 秒以内に 2xx のステータスで答えてください。自分の処理は、答えたあとに行います。それ以外の答え、または答えがない場合は、失敗として扱います。
失敗すると、Crewcade はもう一度送ります。約 27 時間の間に、最大 8 回試します。
| 回数 | 時期 |
|---|---|
| 1 | すぐに |
| 2 | 1 回目の 5 秒後 |
| 3 | 2 回目の 5 分後 |
| 4 | 3 回目の 30 分後 |
| 5 | 4 回目の 2 時間後 |
| 6 | 5 回目の 5 時間後 |
| 7 | 6 回目の 10 時間後 |
| 8 | 7 回目の 10 時間後 |
次の点に備えてください。
- 再試行も再送も、同じ
webhook-idで届きます。処理した ID を保存しておき、見たことのあるメッセージは捨ててください。 - メッセージは順番どおりに届かないことがあります。順番を信じず、
/v1で現在の状態を読み取ってください。 - 各メッセージは少なくとも 1 回届きます。2 回届くこともあります。
- まれにメッセージが届かないことがあります。ときどき
/v1からメンバーとイベントを読み直して、追いつかせてください。
エンドポイントが失敗し続けるとき
Section titled “エンドポイントが失敗し続けるとき”5 日間失敗し続けたエンドポイントは、オフになります。クラブのオーナーにメールが届きます。サーバーを直し、エンドポイントをオンにして、配信ログから届かなかったメッセージを再送してください。
APIキーを無効にすると、そのキーが作ったエンドポイントもオフになります。
シークレットを替える
Section titled “シークレットを替える”エンドポイントのページで、シークレットのローテーションを押します。新しいシークレットは一度だけ表示されます。古いシークレットは 24 時間使えます。その間、各リクエストには 2 つの署名が付きます。メッセージを逃さずに、新しいシークレットへ切り替えられます。
エンドポイントを開くと、配信を見られます。Crewcade は 30 日分を保管します。各配信に、すべての試行のステータスコード、時刻、所要時間が表示されます。あなたのサーバーが返した内容の最初の 1 KB も表示されます。
- 再送 を押すと、終わった配信をもう一度送ります。
- テスト送信 を押すと、
webhook.testメッセージをエンドポイントに送ります。
テストと再送は、1 つのエンドポイントにつき 1 分間に 10 回までです。クラブ全体では 1 日 100 回までです。
API でエンドポイントを管理する
Section titled “API でエンドポイントを管理する”これらのリクエストには、Webhook管理 権限(can_manage_webhooks)を持つ APIキーが必要です。キーが選べるのは、キーと、キーを作った人が受け取れるイベントだけです。
| メソッドとパス | できること |
|---|---|
GET /webhook-endpoints | エンドポイントを新しい順に一覧します。 |
POST /webhook-endpoints | エンドポイントを追加します。シークレットは一度だけ返ります。 |
GET /webhook-endpoints/{endpointId} | 1 つのエンドポイントを読みます。 |
PATCH /webhook-endpoints/{endpointId} | アドレス、説明、イベントを変えます。 |
DELETE /webhook-endpoints/{endpointId} | エンドポイントと配信ログを削除します。 |
POST /webhook-endpoints/{endpointId}/enable | エンドポイントをオンにします。 |
POST /webhook-endpoints/{endpointId}/disable | エンドポイントをオフにします。 |
POST /webhook-endpoints/{endpointId}/rotate-secret | 新しいシークレットを作ります。古いものは 24 時間使えます。 |
POST /webhook-endpoints/{endpointId}/test | テストメッセージを送ります。 |
GET /webhook-endpoints/{endpointId}/deliveries | 過去 30 日の配信を一覧します。 |
GET /webhook-endpoints/{endpointId}/deliveries/{deliveryId} | 1 つの配信を、すべての試行と送った本文つきで読みます。 |
POST /webhook-endpoints/{endpointId}/deliveries/{deliveryId}/resend | 終わった配信をもう一度送ります。 |
エンドポイントを追加する例です。
curl https://api.crewcade.com/api/v1/webhook-endpoints \ -X POST \ -H "Authorization: Bearer cck_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/hooks/crewcade", "description": "Sync signups", "eventTypes": ["registration.created", "registration.cancelled"] }'{ "endpoint": { "id": "whe_123", "url": "https://example.com/hooks/crewcade", "status": "enabled", "eventTypes": ["registration.created", "registration.cancelled"] }, "secret": "whsec_your_secret_here"}返事にはこれ以外の項目もあります。OpenAPI 仕様を見てください。
| ステータス | コード | 意味 |
|---|---|---|
| 400 | webhook_url_https_required | アドレスが https ではありません。 |
| 400 | webhook_url_blocked_address | アドレスがプライベート、ローカル、または内部のものです。 |
| 400 | webhook_url_credentials_forbidden | アドレスにユーザー名かパスワードが入っています。 |
| 400 | webhook_url_invalid | 正しいウェブアドレスではありません。 |
| 400 | webhook_url_unresolvable | アドレスの先にサーバーが見つかりません。 |
| 403 | api_key_permission_missing | キーに Webhook管理 権限がありません。 |
| 403 | webhook_permission_missing | イベントに必要な権限を、キーまたはキーを作った人が持っていません。 |
| 403 | webhook_creator_permission_missing | エンドポイントを作った人が、イベントに必要な権限を持っていません。 |
| 409 | webhook_endpoint_limit | クラブにはすでに 10 件のエンドポイントがあります。 |
| 409 | webhook_delivery_in_progress | 配信がまだ送信中です。終わってから再送してください。 |
| 429 | webhook_send_limited | テストや再送が多すぎます。Retry-After ヘッダーの秒数だけ待ってください。 |
| 429 | rate_limited | リクエストが多すぎます。Retry-After ヘッダーの秒数だけ待ってください。 |
403 の本文には missingPermissions が入ります。