Webhook

Cloud Paper が外へ送るのは、コントロールパネルで登録した「送信先」だけ。

送り方

• 通知は、管理画面で登録した送信先（https の URL）へ POST で送ります。
• 1 回の試行は 10 秒で切れます。2xx 以外・時間切れは再送します。
• 再送は最大 6 回（最初 + 再試行 5 回）。間隔は 30 秒・2 分・10 分・30 分・2 時間。再送のたびに新しい時刻で署名し直します。
• それでも届かなければ「失敗」にして、管理画面のダッシュボード・送信先・履歴に出します。
• 同じ送信先へは、積んだ順に送ります（再送があると前後しえます）。本文は 900 KiB まで。

7.2 登録できる送信先

パネルの「送信先」だけで登録する（所有者・管理者）。API では足せない。

• https・ポート 443・普通のドメイン名だけ。
  • IP アドレスはどの書き方でも不可（2130706433・0x7f.1・127.1 なども）。
  • 2 つ以上のラベル、最後のラベルは英字だけ、小文字の ASCII。
  • 内部・予約の名前は不可: .localhost .local .internal .lan .home.arpa .localdomain .test .example .invalid .onion .intranet .corp、と cloudpaper.appz.jp の下。
  • 利用者名・パスワード・#・制御文字・\ を含む URL、500 文字超は不可。
• リダイレクトへは移動しない。
• 1 テナント 20 件まで。名前は 64 文字まで、重複不可。
• 通知する出来事を選ぶ: item.received・job.finished・call.incoming・item.ocr.started・item.ocr.done・item.ocr.failed・item.ocr.skipped・item.recognized（OCR は OCR と書類の認識）。
• 書類の出来事（item.received・item.ocr.*・item.recognized）は、書類を届ける受け口を選ぶ（* = すべて）。
• 書類そのものは送らない。通知と署名つきの URL だけ。
• 秘密（whs_…）は、登録・作り直しの直後に一度だけ表示する。サーバーは封をして保存する。

パネルでできること: 有効・無効、削除、テスト送信（1 テナント 1 時間 10 回まで）、秘密の作り直し（古い署名はすぐ通らなくなる）、最近の送信の確認。 閲覧のみの利用者には、URL のホストだけを見せる。

7.3 受け取り側が確かめること

POST <登録した URL>
Content-Type: application/json
X-CloudPaper-Event: item.received
X-CloudPaper-Timestamp: <unix 秒>
X-CloudPaper-Signature: sha256=<hex(HMAC-SHA256(秘密, timestamp + "." + 本文))>

• 署名を必ず検証する。 時刻が数分以内であることも確かめる。
• delivery_id（署名された本文の中）で重複を除ける。
• 2xx 以外・時間切れは再送される。

7.4 通知の本文

すべての通知に event と tenant が入る。配送（再送つき）の通知には delivery_id（dlv_…）も入る。

item.received

{"event":"item.received","tenant":"acme","delivery_id":"dlv_01JA2B3C4D5E6F7G8H9JKMNPQR",
 "inbox":"受付","item_id":"itm_01JA…","kind":"scan|fax|file|photo","caller":"","size":12345,"mime":"application/pdf",
 "sha256":"…","filename":"…","source":"…","at":1760000000,
 "ocr":{"ocr_id":"ocr_01JA…","status":"queued","pages_total":0,"pages_done":0,"tables":0,"url":"https://acme.cloudpaper.appz.jp/api/v1/items/itm_01JA…/ocr"},
 "download_url":"https://acme.cloudpaper.appz.jp/dl/<item>?c=<送信先>&exp=…&sig=…",
 "ack_url":"https://acme.cloudpaper.appz.jp/dl/<item>?c=<送信先>&exp=…&sig=…&ack=1"}

ocr は、OCR をする受け口の書類だけに入る。受け口が after_ocr なら、item.received は OCR が終わってから届き、ocr に結果の要約（status・code・message）が入る（OCR と書類の認識 の 20.5）。

item.recognized

text+tables+recognize の受け口で、書類の種類が決まり項目を抜き出したとき（item.ocr.done のあと）。項目の値は入らない（fields_url の API で読む）。

{"event":"item.recognized","tenant":"acme","delivery_id":"dlv_…","inbox":"受付","item_id":"itm_…","ocr_id":"ocr_…",
 "document_type":"business_card","fields":12,"needs_review":true,"at":1760000000,"fields_url":"https://acme.cloudpaper.appz.jp/api/v1/items/itm_…/fields"}

item.ocr.started・item.ocr.done・item.ocr.failed・item.ocr.skipped

{"event":"item.ocr.failed","tenant":"acme","delivery_id":"dlv_…",
 "inbox":"受付","item_id":"itm_…","ocr_id":"ocr_…","ocr_status":"unreadable","code":"unreadable","message":"読めませんでした",
 "pages_total":2,"pages_done":0,"tables":0,"at":1760000000,"ocr_url":"https://acme.cloudpaper.appz.jp/api/v1/items/itm_…/ocr"}

出来事	ocr_status	code
item.ocr.started	running	—
item.ocr.done	done・partial	—
item.ocr.failed	unreadable・failed	unreadable・ocr_failed・ocr_timeout・ocr_unavailable・unsupported_document
item.ocr.skipped	skipped	quota_exceeded・plan_disabled（契約の都合。読み取りの失敗ではない）

書類・文字・取得のリンクは入らない。結果はテナントの API（ocr_url）で読む。

job.finished

{"event":"job.finished","tenant":"acme","delivery_id":"dlv_…",
 "job_id":"…","state":"done|refused|failed","detail":"…","destination":"…","user":"…",
 "label":"…","request_id":"…","pages":2,"copies":1,"fax_to":"******5678"}

call.incoming

{"event":"call.incoming","tenant":"acme","delivery_id":"dlv_…",
 "call_id":"…","number":"0312345678","name":"…","line":"…","reason":"","device_id":"…","at":1760000000}

番号は個人情報として扱うこと。

connection.test

パネルの「テスト」で送る。{"event":"connection.test","tenant":…,"delivery_id":…,"message":"…","at":…}。

7.5 書類の取得と確認

1. download_url（15 分有効）を GET。Content-Disposition: attachment、X-Content-SHA256。
2. sha256 を照合する。
3. ack_url（1 時間有効）に POST。→ 204。ダウンロード用とは別の署名なので、ダウンロードの URL だけでは確認（＝削除）できない。

• 署名は HMAC-SHA256(送信先の秘密, "<dl|ack>|<item>|<送信先 ID>|<exp>")。
• 期限切れ・署名違い・送信先が無効・その受け口が送信先に向いていない・品目が未確認でない、はすべて 404。
• IP ごとに 1 分 120 回まで（超えると 429）。
• 送信先が複数あるときは、その受け口に向いた有効な送信先が全部確認した時点で、品目が「確認済み」になる。

期限が切れたら、テナントの API（GET /api/v1/items/{id}/file）で取れる。