本文へ移動

API ドキュメント

v1.0.0

イベント

Webhook は、チームメンバーがフォローし webhook 配信を有効にしている案件のイベントに加え、新しい破産とポートフォリオの一致を受信します。

イベント
イベント発生条件
case.created新しい破産または支払猶予
case.status_changed廃止、終了、その他の状況の変更
report.published新規または差し替えられた公開報告書
report.processed報告書の処理が完了し、変更が利用可能
value.corrected報告を受けてデータが訂正された
value.conflictあるデータについて出典の内容が食い違っている
portfolio.hitポートフォリオ内の KvK 番号が破産した(完全一致のみ)
auction.linkedフォロー中の案件にオークションが関連付けられた

配信

各配信は JSON を含む POST です。Faillissement-Delivery と Faillissement-Event ヘッダーで ID とイベントを示します。

POST /hooks/faillissement HTTP/1.1
Content-Type: application/json
Faillissement-Delivery: 01M3MRB2Q8W5Y1T6V9X3Z7C4N0
Faillissement-Event: report.published
Faillissement-Signature: t=1790592000,v1=5f2b…9a1c

{
  "id": "01M3MRB2Q8W5Y1T6V9X3Z7C4N0",
  "event": "report.published",
  "created_at": "2026-09-26T09:40:12+02:00",
  "data": {
    "case": {
      "id": "01M3MR667REBMJEMXA8R6NS3YZ",
      "name": "Jansen Bouw B.V.",
      "kvk_number": "12345678",
      "insolvency_number": "F.05/25/184",
      "status": "active",
      "links": { "self": "https://api.faillissement.app/api/v1/cases/01M3MR667REBMJEMXA8R6NS3YZ" }
    },
    "event": { "id": "01M3MR69…", "type": "report_published", "occurred_at": "2026-09-26T09:40:00+02:00", "details": {} }
  }
}

署名の検証

Faillissement-Signature ヘッダーには、カンマで区切られた t(Unix 時刻)と v1(署名)が含まれます。署名は、時刻、ピリオド、生のボディを連結したものに対し、webhook のシークレットで計算した HMAC-SHA256 です。常に生のボディで検証し、5分より古い時刻は拒否してください。

import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(part => part.split('=')))
  if (!Number.isFinite(Number(parts.t)) || !/^[a-f0-9]{64}$/.test(parts.v1 ?? '')) return false
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')

  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ''))
}

再配信

サーバーが 10 秒以内に 2xx ステータスで応答しない場合、間隔を延ばしながら最大 6 時間にわたり、さらに 5 回再試行します。20 回連続で配信に失敗すると、webhook を無効にしてメールでお知らせします。重複した配信は delivery ID で識別してください。