Создание вебхука

POST /v1/webhooks

Регистрация URL вебхука для получения POST-запросов при возникновении событий извлечения. Каждый пользователь может иметь до 10 активных вебхуков.

Попробуйте

Протестируйте этот эндпоинт интерактивно в Swagger UI.

Требуется авторизация

Укажите ваш API-ключ в заголовке Authorization.

Запрос

Заголовки

Заголовок	Значение	Обязательно
Authorization	Bearer <token>	Да
Content-Type	application/json	Да

Тело запроса

Поле	Тип	Обязательно	Описание
url	string	Да	HTTPS-эндпоинт, который будет получать POST-запросы вебхука.
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 шестнадцатеричных символа). Показывается только один раз.
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-ключ / токен.