コンテンツにスキップ

Webhook

Webhook は、Crewcade があなたのサーバーに送るメッセージです。クラブで何かが変わったときに届きます。たとえば、メンバーがイベントに申し込んだとき、メンバーが参加したとき、イベントが変わったときです。何度も問い合わせる必要はありません。

メッセージには ID だけが入ります。名前やメールアドレスは入りません。詳しい内容は、メンバー、イベント、申し込みのエンドポイントで、あなたのサーバーが読み取ります。

エンドポイントは、あなたのサーバーのウェブアドレスです。受け取りたいイベントも一緒に選びます。オーナーと管理者が追加できます。Webhook管理 権限を持つ役割の人も追加できます。

  1. 設定 を開き、開発者 を選びます。Webhook タブを開きます。
  2. エンドポイントの追加を押します。
  3. サーバーの https アドレスを入力します。
  4. 受け取りたいイベントを選びます。必要なら説明を入れます。
  5. エンドポイントを保存します。
  6. シークレットをコピーします。シークレットは 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イベント名。
timestampCrewcade がメッセージを作った時刻。UTC の ISO-8601 形式。
data変わったものを指す ID。type によって変わります。
{
"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 のこともあります。
{
"id": "msg_9Bd4fGh2JkLm6NpQr8StVw1X",
"type": "member.updated",
"timestamp": "2026-11-12T02:00:00.000Z",
"data": {
"memberId": "mem_456",
"source": null
}
}
{
"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 のどれかです。

繰り返しのイベントには、たくさんの日程があります。日程ごとに、8 文字の occurrenceId があります。これは GET /events が返す id と同じです。すべての日程は 1 つの seriesId を共有します。日程、シリーズ、IDを見てください。

シリーズ全体が変わったときは、occurrenceId が null です。すべての日程を読むには、その seriesId を付けて GET /events?seriesId= を呼びます。

ID を使い、APIキーで現在の状態を読み取ります。

Terminal window
curl https://api.crewcade.com/api/v1/events/k3m9x2pq \
-H "Authorization: Bearer cck_your_key_here"

Crewcade は、すべてのメッセージに署名します。メッセージを信頼する前に、署名を確認してください。あなたのアドレスには、誰でもリクエストを送れます。シークレットを持っているのは Crewcade だけです。

Crewcade は Standard Webhooks のルールに従います。リクエストには 3 つのヘッダーがあります。

ヘッダー意味
webhook-idメッセージの ID。再送しても同じです。
webhook-timestampCrewcade がリクエストを送った時刻。1970 年からの秒数です。
webhook-signature署名。v1, のあとに base64 が続きます。署名が 2 つあるときは、スペースで区切ります。

メッセージを確認する手順です。

  1. リクエストの生の本文を読みます。解析して書き直さないでください。
  2. webhook-id、webhook-timestamp、生の本文を、間にドットを入れてつなぎます。結果は ${id}.${timestamp}.${rawBody} です。
  3. そのテキストの HMAC-SHA256 を作ります。鍵は、シークレットの whsec_ のあとの部分を base64 から戻したものです。
  4. 結果を base64 にします。それぞれの v1 署名と比べます。
  5. タイムスタンプが 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 にあります。署名とタイムスタンプを代わりに確認してくれます。

10 秒以内に 2xx のステータスで答えてください。自分の処理は、答えたあとに行います。それ以外の答え、または答えがない場合は、失敗として扱います。

失敗すると、Crewcade はもう一度送ります。約 27 時間の間に、最大 8 回試します。

回数時期
1すぐに
21 回目の 5 秒後
32 回目の 5 分後
43 回目の 30 分後
54 回目の 2 時間後
65 回目の 5 時間後
76 回目の 10 時間後
87 回目の 10 時間後

次の点に備えてください。

  • 再試行も再送も、同じ webhook-id で届きます。処理した ID を保存しておき、見たことのあるメッセージは捨ててください。
  • メッセージは順番どおりに届かないことがあります。順番を信じず、/v1 で現在の状態を読み取ってください。
  • 各メッセージは少なくとも 1 回届きます。2 回届くこともあります。
  • まれにメッセージが届かないことがあります。ときどき /v1 からメンバーとイベントを読み直して、追いつかせてください。

エンドポイントが失敗し続けるとき

Section titled “エンドポイントが失敗し続けるとき”

5 日間失敗し続けたエンドポイントは、オフになります。クラブのオーナーにメールが届きます。サーバーを直し、エンドポイントをオンにして、配信ログから届かなかったメッセージを再送してください。

APIキーを無効にすると、そのキーが作ったエンドポイントもオフになります。

エンドポイントのページで、シークレットのローテーションを押します。新しいシークレットは一度だけ表示されます。古いシークレットは 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終わった配信をもう一度送ります。

エンドポイントを追加する例です。

Terminal window
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 仕様を見てください。

ステータスコード意味
400webhook_url_https_requiredアドレスが https ではありません。
400webhook_url_blocked_addressアドレスがプライベート、ローカル、または内部のものです。
400webhook_url_credentials_forbiddenアドレスにユーザー名かパスワードが入っています。
400webhook_url_invalid正しいウェブアドレスではありません。
400webhook_url_unresolvableアドレスの先にサーバーが見つかりません。
403api_key_permission_missingキーに Webhook管理 権限がありません。
403webhook_permission_missingイベントに必要な権限を、キーまたはキーを作った人が持っていません。
403webhook_creator_permission_missingエンドポイントを作った人が、イベントに必要な権限を持っていません。
409webhook_endpoint_limitクラブにはすでに 10 件のエンドポイントがあります。
409webhook_delivery_in_progress配信がまだ送信中です。終わってから再送してください。
429webhook_send_limitedテストや再送が多すぎます。Retry-After ヘッダーの秒数だけ待ってください。
429rate_limitedリクエストが多すぎます。Retry-After ヘッダーの秒数だけ待ってください。

403 の本文には missingPermissions が入ります。