API トークンと Webhook
- アプリ管理者
- 全体管理者
アプリ管理者（アプリごとの設定）／全体管理者（Webhook の全体停止）
外部のシステムから、アプリのレコードを読み書きしたいときは「API トークン」を、アプリの出来事を外部へ知らせたいときは「Webhook」を使います。どちらも、アプリ設定の「設定」タブにある「連携」で設定します。
新しく追加した Webhook は、初期状態では無効です。「有効（公開後）」にチェックを入れて、公開します。
API トークンを発行する
- 「アプリ設定」の「設定」タブから、「連携」を開きます。
- 「APIトークン」で、「名前」を入力します。
- 必要なら、「有効期限」を設定します。
- 使える操作（scope）にチェックを入れます。
| scope | 内容 |
|---|---|
| 閲覧 | レコードを読む |
| 追加 | レコードを追加する |
| 編集 | レコードを編集する |
| 削除 | レコードを削除する |
| CSV取込 | CSV を読み込む |
| CSV書出 | CSV を書き出す |
- 「トークンを発行（即時）」を押します。
- トークンの値が確認できるのは、発行した直後の画面だけです。再表示はできません。安全な保管先へ移してください。
- 各操作には、トークンの scope と、発行した人の現在のアクセス権の、両方が必要です。
- 発行・失効は、「変更を反映」を待たずに、すぐに反映されます。
トークンを失効する
一覧の「失効（即時）」を押すと、そのトークンはすぐに使えなくなります。有効期限が切れたトークンは、「期限切れ」と表示されます。
Webhook を設定する
Webhook は、アプリでレコードの追加などがあったときに、決めた URL へ通知を送る仕組みです。
- 「連携」の「Webhook設定」で、「Webhookを追加」を押します。
- 「名前」を入力します。
- 「HTTPS URL」に、送信先を入力します。https で始まる URL が必要です。
- 通知するイベントを選びます。
- 「有効（公開後）」にチェックを入れます。
- 「下書きを保存」を押し、「変更を反映」で公開します。
- 「署名鍵を発行・更新（即時）」を押し、署名鍵を発行します。
選べるイベントは、追加・更新・コメント・いいね・プロセス・担当・CSV取込・CSV書出です。削除のイベントは、削除したあとに、閲覧の権限を確認できないため、送信されません。
- 1 つのアプリに、Webhook を 20 件まで設定できます。
- 公開済みの URL とイベント、署名鍵がそろった Webhook だけが、送信の対象になります。
- 署名鍵の値も、発行した直後の画面だけで確認できます。「署名鍵を失効（即時）」で、失効できます。
- Webhook を削除するときは、「設定を削除」を押し、「変更を反映」します。
Webhook の送信内容と署名
Webhook は、決めた URL へ、POST で送られます。「Content-Type」は「application/json; charset=utf-8」です。次のヘッダーが付きます。
| ヘッダー | 内容 |
|---|---|
| X-BlockStudio-Delivery | 配送の ID |
| X-BlockStudio-Event | イベント名 |
| X-BlockStudio-Timestamp | 送信時刻（UNIX 秒） |
| X-BlockStudio-Signature | 署名。「sha256=」のあとに、16 進の文字列が続きます。 |
署名は、署名鍵を使った HMAC-SHA256 です。署名の対象は、「タイムスタンプ.配送ID.本文」を、この順につないだ文字列です。受け取る側で同じ計算をして、署名が一致するかを確認してください。
本文は JSON で、次の内容が入ります。
- eventId、deliveryId、event、appId、recordId、actorId、origin
- レコードがあるイベントでは、record（閲覧の権限で見られない項目を除いたデータ）
本文は 256 KiB までです。送信に失敗したときは、最大 5 回、再試行されます。
API を使う
アプリのレコードは、API で読み書きできます。
- 宛先:
POST /api/app-api/<アプリID> - ヘッダー:
Content-Type: application/jsonと、Authorization: Bearer mat_…（発行した API トークン） - 本文: JSON で、
{"action": …}の形で、操作を指定します。
使える action は、次のとおりです。
| action | 内容 | 必要な scope |
|---|---|---|
| listRecords、getRecord、listComments、listHistory | レコード・コメント・履歴を読む | 閲覧 |
| saveRecord | recordId がなければ追加、あれば編集 | 追加、編集 |
| deleteRecord | レコードを削除する | 削除 |
| importCsv | CSV を読み込む | CSV取込 |
| exportCsv | CSV を書き出す | CSV書出 |
本文は、約 1 MB までです。1 つのアプリで有効にできる API トークンは、100 個までです。
実行ログと再送
「連携」の「Webhook実行ログ」で、送信の記録を確認できます。アプリ管理者だけが見られます。
- 表示されるのは、日時、Webhook の名前、送信先のスキーム・ホスト・ポート、イベント、状態、試行回数、最後のエラーです。送信先のパスやクエリ、署名鍵、送信の内容は表示されません。
- 状態で、絞り込めます。
- 状態が「失敗」か「破棄」の行は、再送のアイコンで再送できます。再送は、再送した時点の設定と、レコードの現在の内容で行われます。URL を変えたあとに再送すると、新しい URL に、現在の内容が届きます。
全体停止（全体管理者）
障害のときなどに、全体管理者は、すべての Webhook の送信を止められます。システム管理の「モニタリング」にある「Webhook」で、「Webhook を全体停止」を押します。停止中も、新しい出来事は送信待ちとして残ります。解除するときに、保留中の送信を、「再送」するか「破棄」するかを選びます。破棄した送信は、アプリの実行ログから、個別に再送できます。
詳しくは「全体管理者の設定」を見てください。
アプリを削除したとき
アプリをごみ箱へ移すと、送信待ちの Webhook は破棄されます。復旧しても、戻りません。トークンと Webhook は、復旧すると、すぐに有効に戻ります。トークンが漏れた場合は、アプリを削除する前に、失効してください。