웹훅 생성

POST /v1/webhooks

추출 이벤트 발생 시 POST 요청을 수신할 웹훅 URL을 등록합니다. 각 사용자는 최대 10개의 활성 웹훅을 보유할 수 있습니다.

사용해 보기

이 엔드포인트를 Swagger UI에서 대화형으로 테스트할 수 있습니다.

인증 필요

Authorization 헤더에 API 키를 포함하세요.

요청

헤더

헤더	값	필수
Authorization	Bearer <token>	예
Content-Type	application/json	예

본문

필드	타입	필수	설명
url	string	예	웹훅 POST 요청을 수신할 HTTPS 엔드포인트.
events	string[]	예	구독할 이벤트. 최소 하나 필요. 값: "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()

// IMPORTANT: Store the signing secret immediately — it cannot be retrieved later
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"]

# IMPORTANT: Store the signing secret immediately — it cannot be retrieved later
print(f"Signing Secret: {data['secret']}")
print(f"Webhook ID: {data['webhook']['id']}")

응답

상태: 200 OK

응답 본문은 data 객체로 감싸져 있습니다.

WARNING

서명 시크릿은 이 응답에서만 반환됩니다. 즉시 안전하게 저장하세요 -- 이후에는 조회할 수 없습니다. 웹훅 서명을 검증하는 데 필요합니다.

필드

필드	타입	설명
secret	string	HMAC-SHA256 서명 시크릿 (64자 16진수). 한 번만 표시됩니다.
webhook	object	웹훅 메타데이터 객체 (아래 참조).

webhook 객체:

필드	타입	설명
id	string	웹훅의 고유 식별자.
userId	string	웹훅을 소유한 사용자의 ID.
url	string	등록된 엔드포인트 URL.
events	string[]	웹훅이 구독한 이벤트.
active	boolean	웹훅이 활성 상태인지 여부. 새로 생성된 웹훅의 경우 항상 true.
createdAt	string	웹훅이 생성된 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	최대 10개의 활성 웹훅에 도달했습니다. 새 웹훅을 생성하기 전에 기존 웹훅을 삭제하세요.
401	UNAUTHORIZED	누락, 유효하지 않거나 만료된 API 키 / 토큰.