CastingONE API Specifications (1.0.0)
API の利用にはアクセスキーとアクセストークンが必要です。 アクセスキーとアクセストークンは管理サイトから発行できます。(事前に API 連携の利用申請が必要です) アクセスキーとアクセストークンは、リクエストヘッダに以下のように含めてください。
curl -X GET \ -H 'x-api-key: API_KEY' \ -H 'x-api-token: API_TOKEN' \ https://tn.lb.core.lite.casting-one.jp/
ステージング環境を利用する場合は、上記 URL のホスト名を tn-stg.lb.core.lite.casting-one.jp に差し替えてください。
リストを返す API では一度に返せる要素の数が限定されており、より多くの要素が必要となる場合はページを指定する必要があります。リストの API には、1 から始まるページ番号を表す page パラメータと、1 ページあたりに含まれる要素数を表す per_page パラメータを指定することができます。page の初期値は 1 に設定されています。また、per_page の初期値は 50、per_page の最大値は 100 に設定されています。
また、要素の総件数はレスポンスの total_count で確認できます。例えば候補者の総件数が 1000 件の場合は以下のようなレスポンスになります。
{
"total_count": 1000,
"candidates": [...]
}
Webhook のリクエストが届いたら、リクエストヘッダに含まれる署名を検証してください。この検証により「CastingONE サーバから送信された Webhook リクエストである」、「通信途中で改ざんされていない」ことを確認することができます。
CastingONE サーバでは、Webhook リクエストボディを入力データ、シークレットトークンをハッシュ鍵として HMAC-SHA256 で署名を作成し、X-CastingONE-Signature ヘッダとして付与します。 Webhook リクエストと署名は以下の手順で検証できます。
- 受信した Webhook リクエストボディの文字列を入力データ、Webhook 設定作成時のシークレットトークンをハッシュ鍵として、HMAC-SHA256で署名を生成します。
- 受診した署名(
X-CastingONE-Signature)と、生成した署名を比較します。 - 署名が一致した場合は、Webhook リクエストの処理を行うことができます。
署名が一致しない場合は、リクエストが CastingONE サーバ以外から送信された、通信途中で改ざんされた、あるいは検証手順に誤りがある可能性があります。
Go:
func verifySignature(secretToken string, body []byte, signature string) bool {
hash := hmac.New(sha256.New, []byte(secretToken))
hash.Write(body)
expected := hex.EncodeToString(hash.Sum(nil))
return hmac.Equal([]byte(expected), []byte(signature))
}
Node.js:
const crypto = require("crypto");
function verifySignature(secretToken, body, signature) {
const expected = crypto
.createHmac("sha256", secretToken)
.update(body)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}