Webhookを作成

POST /v1/webhooks

抽出イベントが発生した際にPOSTリクエストを受信するWebhook URLを登録します。各ユーザーは最大10個のアクティブなWebhookを保持できます。

試してみる

このエンドポイントを Swagger UI でインタラクティブにテストできます。

認証が必要です

Authorization ヘッダーにAPIキーを含めてください。

リクエスト

ヘッダー

ヘッダー	値	必須
Authorization	Bearer <token>	はい
Content-Type	application/json	はい

ボディ

フィールド	型	必須	説明
url	string	はい	Webhook POSTリクエストを受信するHTTPSエンドポイント。
events	string[]	はい	購読するイベント。1つ以上必須。値: "extraction.completed"、"extraction.failed"。

コード例

curl

curl -X POST https://api.docmap.io/v1/webhooks \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/docmap",
    "events": ["extraction.completed", "extraction.failed"]
  }'

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://your-app.com/webhooks/docmap',
    events: ['extraction.completed', 'extraction.failed'],
  }),
})

const { data } = await response.json()

// 重要: 署名シークレットをすぐに保存してください — 後で取得することはできません
console.log('Signing Secret:', data.secret)
console.log('Webhook ID:', data.webhook.id)

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

response = requests.post(
    "https://api.docmap.io/v1/webhooks",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://your-app.com/webhooks/docmap",
        "events": ["extraction.completed", "extraction.failed"],
    },
)

data = response.json()["data"]

# 重要: 署名シークレットをすぐに保存してください — 後で取得することはできません
print(f"Signing Secret: {data['secret']}")
print(f"Webhook ID: {data['webhook']['id']}")

レスポンス

ステータス: 200 OK

レスポンスボディは data オブジェクトでラップされています。

WARNING

署名シークレットはこのレスポンスでのみ返されます。すぐに安全に保存してください -- 後で取得することはできません。Webhook署名の検証に必要です。

フィールド

フィールド	型	説明
secret	string	HMAC-SHA256署名シークレット（64桁の16進数文字）。一度だけ表示されます。
webhook	object	Webhookメタデータオブジェクト（下記参照）。

webhook オブジェクト：

フィールド	型	説明
id	string	Webhookの一意の識別子。
userId	string	Webhookを所有するユーザーのID。
url	string	登録されたエンドポイントURL。
events	string[]	Webhookが購読しているイベント。
active	boolean	Webhookがアクティブかどうか。新規作成Webhookの場合は常に true。
createdAt	string	Webhookが作成されたISO 8601タイムスタンプ。

例

{
  "data": {
    "secret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "webhook": {
      "id": "webhook-abc123def456",
      "userId": "uid_a1b2c3d4e5f6",
      "url": "https://your-app.com/webhooks/docmap",
      "events": ["extraction.completed", "extraction.failed"],
      "active": true,
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  }
}

エラー

ステータス	コード	説明
400	MAX_WEBHOOKS_REACHED	アクティブなWebhookの上限10個に達しました。新しいWebhookを作成する前に、既存のWebhookを削除してください。
401	UNAUTHORIZED	APIキー/トークンが欠落、無効、または期限切れです。