ReCORE.co-api

Webhook

概要

• Webhookを利用することで各アプリケーションは、定期的なポーリングを行うことなくリアルタイムで、ReCOREデータとの同期や特定のイベントを元に任意の処理ができます。

ヘッダ

• 各メッセージは下記のような共通のヘッダを持っています。

User-Agent: ReCORE-Webhook
X-ReCORE-Message-ID: e878f0a2-fd3f-5884-b4ac-ae1b74bd0f64:5235
X-ReCORE-Timestamp: 2024-05-11T14:57:06.391Z
X-ReCORE-Company-ID: novasto_demo001
X-ReCORE-Topic: bad.status.changed

key	説明
User-Agent	常にReCORE-Webhook
X-ReCORE-Message-ID	メッセージID
X-ReCORE-Timestamp	送信日時
X-ReCORE-Company-ID	企業ID
X-ReCORE-Topic	トピック

注意事項

送信失敗とリトライについて

• 受信側がHTTPステータスコード200番台以外を返したときは送信失敗とみなされます。
• 5秒以内に応答しなかった場合は送信失敗とみなされます。
• 送信リトライは5秒おきに最大5回繰り返され、それでも送信できなかった場合メッセージは破棄されます。

重複配信について

• ほとんどの場合配信は1回だけ行われますが、稀に同じメッセージが複数回配信される場合があります。
• 冪等性を考慮して設計し、担保できない場合はX-ReCORE-Message-IDを使い、重複排除処理を行ってください。

配信の順序保証について

• ほとんどの場合配信はイベントが発生した順に行われますが、稀に順番が前後して配信される場合があります。
• 配信順序の担保が必要な場合はX-ReCORE-Timestampを使い、適切な実装を行ってください。

トピック

bad.status.changed

概要

• 宅配買取ケースのステータスが変更になったときに通知

body

宅配買取ケース取得とほぼ同様
差分は下記を参照

key	type	説明
goods.*.product	object	カタログ
goods.*.product.id	int	カタログID
goods.*.product.code	string	カタログコード
goods.*.product.alias_code	string | null	代替商品コード
goods.*.product.status	string	ステータス
goods.*.product.title	string	商品名
goods.*.product.image_url	string | null	商品画像URL
goods.*.product.category	object	カテゴリ
goods.*.product.category.id	int	カテゴリID
goods.*.product.category.name	string	カテゴリ名
goods.*.product.category.ancestors	array<object>	親カテゴリ、カテゴリ先頭から並ぶ
goods.*.product.category.ancestors.*.id	int	親カテゴリID
goods.*.product.category.ancestors.*.name	name	親カテゴリ名
goods.*.product.created_at	int | null	作成日時
goods.*.product.updated_at	int | null	更新日時

bad.return_status.changed

概要

• 宅配買取ケースの返送ステータスが変更になったときに通知

body

bad.status.changedと同様

identification.status.changed

概要

• 本人確認のステータスが変更になったときに通知

body

本人確認取得と同様

provider.gmo_bank.status.changed

概要

• GMO銀行振込のステータスが変更になったときに通知

body

GMO銀行振込取得と同様

provider.pickup.status.changed

概要

• ヤマト集荷のステータスが変更になったときに通知

body

{
  "id": 2,
  "status": "COLLECTING",
  "tracking_number": null,
  "pickup_date": "2024-06-09",
  "pickup_time": "16",
  "referable_id": 40,
  "referable_type": "rt_bad",
  "closing_at": 1717797600,
  "created_at": 1717819826,
  "updated_at": 1717821794
}

key	type	説明
id	int	集荷ID
status	string	ステータス
tracking_number	string | null	問い合わせ番号
pickup_date	string	集荷日時
pickup_time	string | null	集荷時間コード 宅配買取の希望集荷時間帯コード表を参照
referable_id	int | null	関連先ID
referable_type	string | null	関連先タイプ
closing_at	int | null	変更締め日時
created_at	int | null	作成日時
updated_at	int | null	更新日時

• ステータス
  • PENDING 依頼中
  • COLLECTING 集荷中
  • COLLECTED 集荷済み
  • DONE 配達完了
  • FAILED エラー

member.created

概要

• 会員が作成されたときに通知

body

会員取得と同様

member.updated

概要

• 会員が更新されたときに通知
• 会員ポイントが更新されたときに通知

body

会員取得と同様

Webhook登録API

登録済みWebhook検索

概要

• 登録済みWebhookの検索を行う

基本情報

• リクエストパス: GET /webhooks
• JWTスコープ: webhook:index
• 必須個別JWTパラメータ: なし
• レートリミット: 5 rps

query

なし

例

• Request

GET /webhooks

• Response

[
  {
    "id": "01HXM1FRZY28Q8QE6A1F984GA0",
    "address": "https://example.com",
    "topics": [
      "bad.status.changed"
    ]
  }
]

key	type	説明
*	array<object>	Webhook
*.id	string	WebhookID
*.address	string	配信先URL
*.topics	array<string>	受信トピック

登録済みWebhook取得

概要

• 登録済みWebhookを1件取得する

基本情報

• リクエストパス: GET /webhooks/{webhook_id}
• JWTスコープ: webhook:show
• 必須個別JWTパラメータ: なし
• レートリミット: 5 rps

例

• Request

GET /webhooks/01HXM1FRZY28Q8QE6A1F984GA0

• Response

登録済みWebhook検索のresponse[0]と同様

Webhook登録

概要

• Webhookを登録する

基本情報

• リクエストパス: POST /webhooks
• JWTスコープ: webhook:store
• 必須個別JWTパラメータ: なし
• レートリミット: 2 rps

body

key	type	説明	制約など
address	string	配信先URL	-
topics	array<string>	受信トピック	-

例

• Request

POST /webhooks

{
  "address": "https://example.com",
  "topics": [
    "bad.status.changed"
  ]
}

• Response

登録済みWebhook取得と同様

登録済みWebhook更新

概要

• 登録済みWebhookを更新する

基本情報

• リクエストパス: PUT /webhooks/{webhook_id}
• JWTスコープ: webhook:update
• 必須個別JWTパラメータ: なし
• レートリミット: 2 rps

body

key	type	説明	制約など
address	?string	配信先URL	-
topics	?array<string>	受信トピック	-

例

• Request

PUT /webhooks/01HXM1FRZY28Q8QE6A1F984GA0

{
  "address": "https://example.com",
  "topics": [
    "bad.status.changed"
  ]
}

• Response

登録済みWebhook取得と同様

登録済みWebhook削除

概要

• 登録済みWebhookを削除する

基本情報

• リクエストパス: DELETE /webhooks/{webhook_id}
• JWTスコープ: webhook:destroy
• 必須個別JWTパラメータ: なし
• レートリミット: 2 rps

例

• Request

DELETE /webhooks/01HXM1FRZY28Q8QE6A1F984GA0

• Response

なし