Webhook 連携
Webhook を使えば、ポーリングすることなく、今後の収集日をあらゆるシステムに能動的に通知できます。設定した日数後に収集が予定されると、binable があなたの URL に HTTP POST を送信します。
Webhook は API から直接作成・削除できます。活用例：n8n／Make による自動化、Discord や Slack のボット、ntfy.sh の通知、ホームオートメーションシステム、独自のアプリケーションなど。
1. API キーを作成
Webhook を作成するには、まず API キーが必要です。メールアドレスを登録すると、API キーがメールで届きます。
2. Webhook を作成
ヘッダーに API キーを付けて、/api/webhook に POST リクエストを送信します。住所はリクエストボディで直接渡します。
curl -X POST https://binable.app/api/webhook \
-H "Authorization: ApiKey <dein-api-key>" \
-H "Content-Type: application/json" \
-d '{
"url": "https://mein-server.example/webhook",
"daysBeforeCollection": 1,
"street": "Musterstraße",
"houseNumber": "1a",
"zip": "12345",
"city": "Musterstadt",
"country": "DE"
}'レスポンスには Webhook の id と secret が含まれます：
{
"id": "018f1e2a-3b4c-7d5e-8f9a-0b1c2d3e4f56",
"url": "https://mein-server.example/webhook",
"secret": "a3f8b1c2d4e5...",
"daysBeforeCollection": 1,
"active": true
}
secret が返されるのは Webhook の作成時の 1 回だけです。署名の検証に必要なので、安全な場所に保管してください。
3. ペイロードと署名の検証
設定した日数後に収集が予定されている場合、binable は毎日 18:00 にすべての有効な Webhook へ POST を送信します：
{
"event": "upcoming_collection",
"sent_at": "2024-01-14T18:00:00+00:00",
"days_until": 1,
"address": {
"street": "Musterstraße",
"houseNumber": "1a",
"zip": "12345",
"city": "Musterstadt",
"country": "DE"
},
"collections": [
{ "type": "Restmüll", "date": "2024-01-15" },
{ "type": "Papier", "date": "2024-01-15" }
]
}各リクエストには X-Binable-Signature: sha256=<hmac> ヘッダーが含まれます。Node.js での検証例：
const crypto = require('crypto');
function verifySignature(body, secret, signatureHeader) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(body)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signatureHeader)
);
}4. Webhook を削除
curl -X DELETE https://binable.app/api/webhook/018f1e2a-3b4c-7d5e-8f9a-0b1c2d3e4f56 \
-H "Authorization: ApiKey <dein-api-key>"成功すると、サーバーは HTTP 204（ボディなし）を返します。
