コンテンツにスキップ
Authrim

Webhook管理

概要

Webhook管理APIは、イベント通知用のWebhookエンドポイントを設定・管理するためのエンドポイントを提供します。ユーザー作成、ログイン、ロール変更などのイベントを外部システムに通知できます。

エンドポイント一覧

メソッドエンドポイント説明
GET/api/admin/webhooksWebhook一覧取得
GET/api/admin/webhooks/:idWebhook詳細取得
POST/api/admin/webhooksWebhook作成
PUT/api/admin/webhooks/:idWebhook更新
DELETE/api/admin/webhooks/:idWebhook削除
POST/api/admin/webhooks/:id/testWebhookテスト
GET/api/admin/webhooks/:id/deliveries配信履歴取得
POST/api/admin/webhooks/:id/deliveries/:deliveryId/retry配信リトライ

Webhook一覧取得

設定されているWebhookの一覧を取得します。

エンドポイント

GET /api/admin/webhooks

クエリパラメータ

パラメータ型必須説明
limitinteger-取得件数（デフォルト: 20）
cursorstring-ページネーションカーソル
statusstring-ステータスでフィルタ（active, inactive）

リクエスト例

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/webhooks" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "items": [
    {
      "id": "webhook_abc123",
      "name": "User Events",
      "url": "https://api.example.com/webhooks/authrim",
      "events": ["user.created", "user.updated", "user.deleted"],
      "status": "active",
      "success_rate": 99.5,
      "last_triggered_at": 1706054400,
      "created_at": 1705881600
    }
  ],
  "total": 3
}

Webhook詳細取得

指定されたWebhookの詳細情報を取得します。

エンドポイント

GET /api/admin/webhooks/:id

パスパラメータ

パラメータ型必須説明
idstring○Webhook ID

リクエスト例

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/webhooks/webhook_abc123" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "id": "webhook_abc123",
  "name": "User Events",
  "description": "ユーザー関連イベントの通知",
  "url": "https://api.example.com/webhooks/authrim",
  "events": ["user.created", "user.updated", "user.deleted"],
  "status": "active",
  "headers": {
    "X-Custom-Header": "custom-value"
  },
  "timeout": 30,
  "retry_policy": {
    "max_retries": 3,
    "retry_interval": 60
  },
  "filters": {
    "user.created": {
      "roles": ["admin"]
    }
  },
  "success_rate": 99.5,
  "total_deliveries": 1250,
  "failed_deliveries": 6,
  "last_triggered_at": 1706054400,
  "last_success_at": 1706054400,
  "last_failure_at": 1705968000,
  "created_at": 1705881600,
  "updated_at": 1706054400
}

Webhook作成

新しいWebhookを作成します。

エンドポイント

POST /api/admin/webhooks

リクエストボディ

フィールド型必須説明
namestring○Webhook名
urlstring○エンドポイントURL
eventsstring[]○購読するイベント
descriptionstring-説明
secretstring-署名用シークレット
headersobject-カスタムヘッダー
timeoutinteger-タイムアウト（秒、デフォルト: 30）
retry_policyobject-リトライポリシー
filtersobject-イベントフィルター

リクエスト例

Terminal window
curl -X POST "https://{tenant-domain}/api/admin/webhooks" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Security Events",
    "url": "https://siem.example.com/webhooks/authrim",
    "events": ["auth.login", "auth.login_failed", "auth.logout", "security.alert"],
    "secret": "webhook_secret_123",
    "headers": {
      "X-Source": "authrim"
    },
    "retry_policy": {
      "max_retries": 5,
      "retry_interval": 30
    }
  }'

レスポンス例

{
  "id": "webhook_xyz789",
  "name": "Security Events",
  "url": "https://siem.example.com/webhooks/authrim",
  "events": ["auth.login", "auth.login_failed", "auth.logout", "security.alert"],
  "status": "active",
  "created_at": 1706140800
}

Webhook更新

既存のWebhookを更新します。

エンドポイント

PUT /api/admin/webhooks/:id

リクエスト例

Terminal window
curl -X PUT "https://{tenant-domain}/api/admin/webhooks/webhook_abc123" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["user.created", "user.updated", "user.deleted", "user.suspended"],
    "status": "active"
  }'

Webhook削除

Webhookを削除します。

エンドポイント

DELETE /api/admin/webhooks/:id

リクエスト例

Terminal window
curl -X DELETE "https://{tenant-domain}/api/admin/webhooks/webhook_abc123" \
  -H "Authorization: Bearer {token}"

Webhookテスト

Webhookの設定をテストします。テストイベントが送信されます。

エンドポイント

POST /api/admin/webhooks/:id/test

リクエストボディ

フィールド型必須説明
eventstring-テストするイベント種別

リクエスト例

Terminal window
curl -X POST "https://{tenant-domain}/api/admin/webhooks/webhook_abc123/test" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "user.created"
  }'

レスポンス例（成功）

{
  "success": true,
  "response_status": 200,
  "response_time_ms": 150,
  "response_body": "{\"received\": true}"
}

レスポンス例（失敗）

{
  "success": false,
  "error": "Connection timeout",
  "response_time_ms": 30000
}

配信履歴取得

Webhookの配信履歴を取得します。

エンドポイント

GET /api/admin/webhooks/:id/deliveries

クエリパラメータ

パラメータ型必須説明
limitinteger-取得件数（デフォルト: 50）
cursorstring-ページネーションカーソル
statusstring-ステータス（success, failed, pending）
eventstring-イベント種別でフィルタ

リクエスト例

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/webhooks/webhook_abc123/deliveries?status=failed" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "items": [
    {
      "id": "delivery_abc123",
      "event": "user.created",
      "status": "failed",
      "attempt": 3,
      "response_status": 500,
      "response_time_ms": 2500,
      "error": "Internal Server Error",
      "request_body": {
        "event": "user.created",
        "timestamp": "2024-01-22T10:30:00Z",
        "data": {
          "user_id": "usr_xyz789"
        }
      },
      "triggered_at": 1706054400,
      "completed_at": 1706054403
    }
  ],
  "total": 6,
  "cursor": null
}

配信リトライ

失敗した配信を手動でリトライします。

エンドポイント

POST /api/admin/webhooks/:id/deliveries/:deliveryId/retry

パスパラメータ

パラメータ型必須説明
idstring○Webhook ID
deliveryIdstring○配信ID

リクエスト例

Terminal window
curl -X POST "https://{tenant-domain}/api/admin/webhooks/webhook_abc123/deliveries/delivery_abc123/retry" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "id": "delivery_abc123",
  "status": "pending",
  "retry_at": 1706140800
}

イベント一覧

ユーザーイベント

イベント説明
user.createdユーザー作成
user.updatedユーザー更新
user.deletedユーザー削除
user.suspendedユーザー停止
user.unsuspendedユーザー停止解除

認証イベント

イベント説明
auth.loginログイン成功
auth.login_failedログイン失敗
auth.logoutログアウト
auth.password_changedパスワード変更
auth.mfa_enabledMFA有効化

セキュリティイベント

イベント説明
security.alertセキュリティアラート
security.suspicious_activity不審なアクティビティ

ロール・権限イベント

イベント説明
role.assignedロール割り当て
role.unassignedロール解除
policy.createdポリシー作成
policy.updatedポリシー更新

Webhook署名

Webhookリクエストには署名ヘッダーが含まれます：

X-Authrim-Signature: sha256=xxxxxxxxxxxxxxxxxxxx
X-Authrim-Timestamp: 1706140800

署名の検証：

const crypto = require('crypto');


function verifySignature(payload, signature, secret, timestamp) {
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');


  return `sha256=${expectedSignature}` === signature;
}