Webhook

カスタムウェブフックを設定して、任意のサービスからウェブフックを受信します。

概要

Generic Webhookブロックは、外部サービスからのWebhookを受信することができます。これはあらゆるJSONペイロードを処理できる柔軟なトリガーであり、専用のMandalaブロックを持たないサービスとの統合に最適です。

基本的な使用方法

シンプルなパススルーモード

入力フォーマットを定義しない場合、Webhookはリクエスト本文全体をそのまま渡します：

curl -X POST https://mandala.ayantram.com/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Mandala-Secret: your-secret" \
  -d '{
    "message": "Test webhook trigger",
    "data": {
      "key": "value"
    }
  }'

下流のブロックでデータにアクセスする方法：

<webhook1.message> → "Test webhook trigger"
<webhook1.data.key> → "value"

構造化入力フォーマット（オプション）

入力スキーマを定義して、型付きフィールドを取得し、ファイルアップロードなどの高度な機能を有効にします：

入力フォーマット設定：

[
  { "name": "message", "type": "string" },
  { "name": "priority", "type": "number" },
  { "name": "documents", "type": "files" }
]

Webhookリクエスト：

curl -X POST https://mandala.ayantram.com/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Mandala-Secret: your-secret" \
  -d '{
    "message": "Invoice submission",
    "priority": 1,
    "documents": [
      {
        "type": "file",
        "data": "data:application/pdf;base64,JVBERi0xLjQK...",
        "name": "invoice.pdf",
        "mime": "application/pdf"
      }
    ]
  }'

ファイルアップロード

サポートされているファイル形式

Webhookは2つのファイル入力形式をサポートしています：

1. Base64エンコードファイル

ファイルコンテンツを直接アップロードする場合：

{
  "documents": [
    {
      "type": "file",
      "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA...",
      "name": "screenshot.png",
      "mime": "image/png"
    }
  ]
}

最大サイズ: ファイルあたり20MB
フォーマット: Base64エンコーディングを使用した標準データURL
ストレージ: ファイルは安全な実行ストレージにアップロードされます

2. URL参照

既存のファイルURLを渡す場合：

{
  "documents": [
    {
      "type": "url",
      "data": "https://example.com/files/document.pdf",
      "name": "document.pdf",
      "mime": "application/pdf"
    }
  ]
}

下流ブロックでのファイルへのアクセス

ファイルは以下のプロパティを持つUserFileオブジェクトに処理されます：

{
  id: string,          // Unique file identifier
  name: string,        // Original filename
  url: string,         // Presigned URL (valid for 5 minutes)
  size: number,        // File size in bytes
  type: string,        // MIME type
  key: string,         // Storage key
  uploadedAt: string,  // ISO timestamp
  expiresAt: string    // ISO timestamp (5 minutes)
}

ブロックでのアクセス：

<webhook1.documents[0].url> → ダウンロードURL
<webhook1.documents[0].name> → "invoice.pdf"
<webhook1.documents[0].size> → 524288
<webhook1.documents[0].type> → "application/pdf"

完全なファイルアップロード例

# Create a base64-encoded file
echo "Hello World" | base64
# SGVsbG8gV29ybGQK

# Send webhook with file
curl -X POST https://mandala.ayantram.com/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Mandala-Secret: your-secret" \
  -d '{
    "subject": "Document for review",
    "attachments": [
      {
        "type": "file",
        "data": "data:text/plain;base64,SGVsbG8gV29ybGQK",
        "name": "sample.txt",
        "mime": "text/plain"
      }
    ]
  }'

認証

認証の設定（オプション）

Webhookの設定で：

「認証を要求する」を有効にする
シークレットトークンを設定する
ヘッダータイプを選択する：
- カスタムヘッダー：X-Mandala-Secret: your-token
- 認証ベアラー：Authorization: Bearer your-token

認証の使用

# With custom header
curl -X POST https://mandala.ayantram.com/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Mandala-Secret: your-secret-token" \
  -d '{"message": "Authenticated request"}'

# With bearer token
curl -X POST https://mandala.ayantram.com/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"message": "Authenticated request"}'

ベストプラクティス

構造化のための入力フォーマットを使用する：予想されるスキーマがわかっている場合は入力フォーマットを定義してください。これにより以下が提供されます：
- 型の検証
- エディタでのより良いオートコンプリート
- ファイルアップロード機能
認証：不正アクセスを防ぐため、本番環境のWebhookには常に認証を有効にしてください。
ファイルサイズの制限：ファイルは20MB未満に保つようにしてください。より大きなファイルの場合は、代わりにURL参照を使用してください。
ファイルの有効期限：ダウンロードされたファイルのURLは5分間有効です。すぐに処理するか、長期間必要な場合は別の場所に保存してください。
エラー処理：Webhook処理は非同期です。エラーについては実行ログを確認してください。
テスト：デプロイ前に設定を検証するために、エディタの「Webhookをテスト」ボタンを使用してください。

ユースケース

フォーム送信：ファイルアップロード機能を持つカスタムフォームからデータを受け取る
サードパーティ連携：Webhookを送信するサービス（Stripe、GitHubなど）と接続する
ドキュメント処理：外部システムからドキュメントを受け取って処理する
イベント通知：様々なソースからイベントデータを受け取る
カスタムAPI：アプリケーション用のカスタムAPIエンドポイントを構築する

注意事項

カテゴリ：triggers
タイプ：generic_webhook
ファイルサポート：入力フォーマット設定で利用可能
最大ファイルサイズ：ファイルあたり20MB

Webhook

On this page