ドキュメント

始め方

登録から、受け側で署名を検証するまでの 6 つの手順。

https://app.webhookadmin.com/signup で、メールアドレス・Google・GitHub のどれかで登録します。メールアドレスのときは、ログイン用のリンクがメールで届きます（15 分間有効）。

最初のログインで組織（会社やチームの単位）を作ります。プラン・請求・メンバーは組織ごとです。Free の組織は 1 人 2 つまで作れます。

2. プロジェクト

送る側のサービス 1 つにつき、プロジェクトを 1 つ作ります。プロジェクトには本番とテストの 2 つの環境があります。

環境	API キー	送信数
本番	`sk_live_…`	月の上限と料金の対象
テスト	`sk_test_…`	数えない（1 日 1,000 通まで）

3. API キー

管理画面の「API キー」で、環境ごとに作ります。キーの値は作成したときに 1 回だけ表示されます。権限は次の 5 つから選びます。

権限	できること
`messages:send`	メッセージの送信
`messages:retry`	送信のやり直し
`logs:read`	配信記録・顧客・送信先の参照
`endpoints:write`	送信先の登録・変更・削除、署名の鍵の切り替え
`consumers:write`	顧客の登録

有効期限は 30 日・90 日・1 年・なしから選びます。期限の 7 日前に、組織の Owner と Admin へメールで知らせます。取り消したキーは 30 秒以内に使えなくなります。

このページの見本では、キーを環境変数 WEBHOOK_ADMIN_API_KEY に入れて使います。

export WEBHOOK_ADMIN_API_KEY=sk_test_…

4. 顧客と送信先

顧客は Webhook を受け取る側の会社や利用者です。external_id には、送る側のサービスでの顧客の ID を入れます。

curl https://api.webhookadmin.com/v1/consumers \
  -H "Authorization: Bearer $WEBHOOK_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "cus_1024", "name": "株式会社サンプル" }'

const res = await fetch('https://api.webhookadmin.com/v1/consumers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WEBHOOK_ADMIN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ external_id: 'cus_1024', name: '株式会社サンプル' }),
});
const consumer = await res.json(); // { id: 'con_…', external_id: 'cus_1024', … }

顧客の id を指定して、Webhook を受け取る URL を送信先として登録します。応答の secret（whsec_ で始まる署名の鍵）は、このときだけ返ります。受け側で署名を検証するときに使います。

curl https://api.webhookadmin.com/v1/endpoints \
  -H "Authorization: Bearer $WEBHOOK_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consumer_id": "con_…",
    "url": "https://example.com/webhooks",
    "event_types": ["invoice.paid"]
  }'

const res = await fetch('https://api.webhookadmin.com/v1/endpoints', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WEBHOOK_ADMIN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    consumer_id: consumer.id,
    url: 'https://example.com/webhooks',
    event_types: ['invoice.paid'],
  }),
});
const endpoint = await res.json(); // { id: 'ep_…', secret: 'whsec_…', … }

URL は https、ポートは 443 か 8443。IP アドレスを直接書いた URL・社内アドレスを指す名前は登録できません。
event_types を省くと、すべてのイベントを送ります。
fixed_ip: true にすると、固定の送信元 IP 209.71.107.233 から送ります。受け取る側でこの IP を許可してもらいます。

5. 送信

POST /v1/messages に、顧客の external_id・イベントの種類・本文を送ります。顧客の送信先のうち、そのイベントを受け取るものすべてに届きます。

curl https://api.webhookadmin.com/v1/messages \
  -H "Authorization: Bearer $WEBHOOK_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inv_88-paid" \
  -d '{
    "consumer": "cus_1024",
    "event_type": "invoice.paid",
    "payload": { "invoice_id": "inv_88", "amount": 128000 }
  }'

const res = await fetch('https://api.webhookadmin.com/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WEBHOOK_ADMIN_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'inv_88-paid',
  },
  body: JSON.stringify({
    consumer: 'cus_1024',
    event_type: 'invoice.paid',
    payload: { invoice_id: 'inv_88', amount: 128000 },
  }),
});
const message = await res.json(); // { id: 'msg_…', deliveries: 1 }

応答

HTTP/1.1 202 Accepted

{ "id": "msg_…", "deliveries": 1 }

Idempotency-Key が同じ送信は、24 時間のあいだ最初の id を返し、2 通目は作りません。
external_id の顧客が無いときは、その場で顧客を作ります（送信先が無いので deliveries は 0）。
届いたかどうかは、管理画面の「配信記録」か GET /v1/messages/{id} で見られます。

6. 受け側で署名を検証

送信先には Standard Webhooks の形式の署名を付けて送ります。受け側では公式ライブラリで検証できます。ヘッダーと署名の作り方は署名検証に。

npm install standardwebhooks express

Node.js（Express）

import express from 'express';
import { Webhook } from 'standardwebhooks';

const wh = new Webhook(process.env.WEBHOOK_SECRET); // whsec_…
const app = express();

// 署名は届いた本文そのもので検証するので、JSON に変換する前の本文を受け取る
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = wh.verify(req.body, req.headers);
    console.log(event.type, event.data);
    res.sendStatus(200);
  } catch {
    res.sendStatus(400);
  }
});

app.listen(3000);

WEBHOOK_SECRET には、手順 4 で受け取った whsec_… を入れます。

1. 登録

2. プロジェクト

3. API キー

4. 顧客と送信先

5. 送信

6. 受け側で署名を検証