---
title: セットアップ
description: IDCloud Webhookの設定ステップバイステップガイド — WebおよびSDK向けのポータルセルフサービスと、Checkオーケストレーションを使用するAPI連携向けのクライアント別設定（ブラジルのみ）。
canonical: https://developer.unico.io/ja/dual-api/developers/webhooks-and-events/setup
locale: ja
generated_by: markdown-export
---

IDCloudは、連携方法に応じて2つのWebhookモダリティをサポートしています:

- **Via Portal** — WebおよびSDK連携向け。IDCloudポータルでセルフサービス設定が可能です。
- **By client** — **Checkオーケストレーション**機能を使用するAPI連携向け（非同期フロー）。Unicoチームが設定します。**ブラジルのみ**利用可能です。

### Via Portal（WebおよびSDK）

Webhookエンドポイントを登録または更新するには、IDCloudポータルにアクセスし、**設定 > Webhook** に移動してください。

#### 必要な情報

| フィールド | 説明 |
|---|---|
| **通知URL** | Unicoがイベント通知を配信するために呼び出すエンドポイント。HTTPSでアクセス可能である必要があります。 |
| **認証タイプ** | Unicoがエンドポイントに対して認証する方法。以下のオプションを参照してください。 |
| **リトライ設定** | 最大試行回数と試行間隔（指数バックオフが適用されます）。 |
| **同時実行数制限** | 同時処理中の配信の最大数（最大: **500**）。 |
| **タイムアウト** | エンドポイントのレスポンスの最大待機時間（秒単位）。 |
| **通知するステータス** | 通知をトリガーするプロセス状態のセット。現在は `PROCESS_STATE_FINISHED` に固定されており、この時点では設定変更はできません。 |

#### 認証方法

****OAuth2****

提供するもの:

  - Webhookの`endpoint`
  - OAuth2プロバイダーの`URL`
  - OAuth2プロバイダーの`ClientId`
  - OAuth2プロバイダーの`Secret`

  Unicoはクライアント認証情報を使用してプロバイダーURLからアクセストークンをリクエストし、Bearerトークンとしてエンドポイントに転送します。

****Basic Authorization****

`user:pass`の形式で認証情報を提供してください。UnicはBase64でエンコードし、すべてのWebhook呼び出しの`Authorization: Basic <encoded>`ヘッダーで送信します。

****API Key****

2つの形式がサポートされています。文字列は**最初の**コロンで分割されます:

  - `header:value` — カスタムヘッダー名を設定します。例:
    - `X-API-Key:abc123` → `X-API-Key: abc123`
    - `Authorization:Bearer abc123` → `Authorization: Bearer abc123`
  - `value`のみ（コロンなし） — 値はスキームプレフィックスなしで`Authorization`ヘッダーとして送信されます。例: `abc123` → `Authorization: abc123`。

  Bearerスキームが必要な場合は`header:value`形式を使用してください（例: `Authorization:Bearer <token>`）。値のみの形式はプレフィックスなしで生の値を送信します。

****認証なし****

認証情報は送信されません。開発環境のみで推奨されます。本番環境のエンドポイントは常に認証を要求する必要があります。

#### 通知をトリガーするプロセス状態

現在、Unicoはプロセスが以下の状態に遷移するたびに通知を送信します:

| 状態 | 説明 |
|---|---|
| `PROCESS_STATE_FINISHED` | プロセス完了 — 結果に関わらずの終端状態。 |

:::warning[状態は変化する可能性があります]
プラットフォームから通知される状態のセットは将来変更される可能性があります。エンドポイントが反応する状態を**設定可能**にしてください。そうすることで、新しい状態を追加する際にサービスの再デプロイが不要になります。
:::

#### リクエスト形式

Webhookの配信はエンドポイントへの**POST**リクエストです。ボディにはプロセス識別子と現在の状態が含まれます。

```json
{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}
```

:::note[`lastEvent` と `lastEventDescription`]
これら 2 つのフィールドは、**プロセスがユーザーのジャーニー完了前に期限切れになった場合のみ**ペイロードに表示されます。通常の完了ペイロードには含まれません。完全なスキーマと使用可能な `lastEvent` 値の一覧については、[イベントタイプ](/developers/webhooks-and-events/event-types)を参照してください。
:::

#### 期待されるレスポンス

エンドポイントは**同期的に**レスポンスを返す必要があります:

- **成功**: `200`〜`299`の範囲内の任意のHTTPステータス。
- **失敗**: その他のステータス。Unicoは設定された最大試行回数まで、または`2xx`を受信するまで指数バックオフでリトライします。

:::tip[速やかにレスポンスを返す]
設定されたタイムアウト内にWebhookを迅速に確認応答し（アクノリッジ）、ペイロードの処理は自社側で非同期に行ってください。Webhookハンドラー内での長時間の処理は、タイムアウトや不要なリトライの可能性を高めます。
:::

冪等性とリトライ処理のガイダンスについては、[セキュリティ](/developers/webhooks-and-events/security)を参照してください。

### By client（API — ブラジルのみ）

:::info[ブラジルのみ]
By-client WebhookはブラジルのAPI連携において、**Checkオーケストレーション**機能を使用する場合にのみ利用可能です。これは、プロセス結果が同期APIレスポンスとしてではなく、Webhook経由で配信される非同期フローです。
:::

エンドポイントを登録または更新するには、**CS / オンボーディング**チームにお問い合わせください。

#### 必要な情報

| フィールド | 説明 |
|---|---|
| **通知URL** | ステータス更新を受信するためにシステムが公開するエンドポイント。HTTPSでアクセス可能である必要があります。 |
| **認証タイプ** | Unicoがエンドポイントに対して認証する方法。以下のオプションを参照してください。 |
| **リトライ設定** | 最大試行回数と試行間隔（指数バックオフが適用されます）。 |
| **同時実行数制限** | 同時処理中の配信の最大数（最大: **500**）。 |
| **タイムアウト** | エンドポイントのレスポンスの最大待機時間（秒単位）。 |

#### 認証方法

****OAuth2****

提供するもの:

  - Webhookの`endpoint`
  - OAuth2プロバイダーの`URL`
  - OAuth2プロバイダーの`ClientId`
  - OAuth2プロバイダーの`Secret`

  Unicoはクライアント認証情報を使用してプロバイダーURLからアクセストークンをリクエストし、Bearerトークンとしてエンドポイントに転送します。

****Basic Authorization****

`user:pass`の形式で認証情報を提供してください。UnicoはBase64でエンコードし、すべてのWebhook呼び出しの`Authorization: Basic <encoded>`ヘッダーで送信します。

****API Key****

2つの形式がサポートされています。文字列は**最初の**コロンで分割されます:

  - `header:value` — カスタムヘッダー名を設定します。例:
    - `X-API-Key:abc123` → `X-API-Key: abc123`
    - `Authorization:Bearer abc123` → `Authorization: Bearer abc123`
  - `value`のみ（コロンなし） — 値はスキームプレフィックスなしで`Authorization`ヘッダーとして送信されます。例: `abc123` → `Authorization: abc123`。

  Bearerスキームが必要な場合は`header:value`形式を使用してください（例: `Authorization:Bearer <token>`）。値のみの形式はプレフィックスなしで生の値を送信します。

****認証なし****

認証情報は送信されません。開発環境のみで推奨されます。本番環境のエンドポイントは常に認証を要求する必要があります。

#### ステータスコード

By-client Webhookは**数値ステータスコード**を使用します:

| コード | 説明 |
|---|---|
| `2` | 乖離 — 本人確認チェックで乖離が生じてプロセスが完了しました。 |
| `3` | 完了 — プロセスが正常に完了しました。 |
| `5` | エラー — エラーによりプロセスが終了しました。 |

#### リクエスト形式

Webhookの配信はエンドポイントへの**POST**リクエストです。ボディにはトランザクション識別子と数値ステータスコードが含まれます。

```json
{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": 3
}
```

#### 期待されるレスポンス

エンドポイントは**同期的に**レスポンスを返す必要があります:

- **成功**: `200`〜`299`の範囲内の任意のHTTPステータス。
- **失敗**: その他のステータス。Unicoは設定された最大試行回数まで、または`2xx`を受信するまで指数バックオフでリトライします。

:::tip[速やかにレスポンスを返す]
設定されたタイムアウト内にWebhookを迅速に確認応答し（アクノリッジ）、ペイロードの処理は自社側で非同期に行ってください。Webhookハンドラー内での長時間の処理は、タイムアウトや不要なリトライの可能性を高めます。
:::

:::warning[最低1回の配信保証]
プラットフォームは最低1回の配信を保証します。同じ通知が複数回届く可能性があります。重複を安全に処理するために、`id`フィールドを使用して自社側で冪等性を実装してください。

冪等性とリトライ処理のガイダンスについては、[セキュリティ](/developers/webhooks-and-events/security)を参照してください。
:::