Webhook
店で何かが起きた瞬間に、あなたのサーバーへJSONが届きます。ポーリング不要でリアルタイムに反応できます。
受け取れるイベント (14種)
friend.followed | 友だち追加された |
friend.unfollowed | 友だち解除 (ブロック) された |
reservation.created | 予約が作成された |
reservation.cancelled | 予約がキャンセルされた |
form.submitted | フォームが回答された |
message.received | 友だちからメッセージを受信した (高頻度) |
member.registered | 会員登録された |
member.tier_changed | 会員ランクが変わった |
member.points_added | ポイントが付与された |
member.visited | 来店が記録された |
payment.succeeded | 決済が完了した |
payment.refunded | 返金された |
payment.failed | 決済に失敗した |
test.ping | テスト送信 (ダッシュボードから) |
購読の登録はダッシュボードの 開発者 > Webhook から。REST API (POST /webhook_endpoints) でも登録できます。
届くもの
POST https://example.com/hooks/loku
Loku-Event-Id: evt_01JCFXXXXXXXXXXXXXXXXXXXXX
Loku-Event-Type: friend.followed
Loku-Signature: t=1748131200,v1=5f8a...
{
"id": "evt_01JCFXXXXXXXXXXXXXXXXXXXXX",
"type": "friend.followed",
"api_version": "2026-05-23",
"created": 1748131200,
"livemode": true,
"data": { /* イベント種別ごとの中身 */ }
}Loku-Signature はStripe互換形式です。Standard Webhooks互換ヘッダ (webhook-signature ほか) も併記されるため、既製SDKでも検証できます。
署名を検証する
すべての配信はHMAC-SHA256で署名されます。t (タイムスタンプ) と生のボディを . で繋いだ文字列に対する署名が v1 です。5分以上ずれた配信は拒否してください。
// Node.js
import { createHmac, timingSafeEqual } from 'crypto';
function verify(header, rawBody, secret) {
const t = header.match(/t=(\d+)/)?.[1];
const v1 = header.match(/v1=([0-9a-f]+)/)?.[1];
if (!t || !v1) return false;
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // ±5分
const expected = createHmac('sha256', secret)
.update(`${t}.${rawBody}`).digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}再試行と重複
| 再試行 | 2xx以外の応答は指数バックオフで最大7回再送します。処理は3秒以内に2xxを返し、重い処理は非同期に回してください。 |
| 重複排除 | 配信は「少なくとも1回」です。Loku-Event-Id で重複を捨ててください。 |
| 自動無効化 | 連続50回失敗した購読は自動で無効になります。配信ログはダッシュボードの 開発者 > Webhook で確認できます。 |
| secretのローテーション | ローテーション中は旧secretも24時間有効です。 |