Вебхуки

Обзор

Вебхуки позволяют получать уведомления в реальном времени о завершении или неудаче извлечений. Вместо опроса API, DocMap отправляет POST-запрос на ваш эндпоинт с результатом извлечения сразу после изменения статуса.

Основные факты:

• Максимум 10 активных вебхуков на аккаунт
• Полезная нагрузка подписывается HMAC-SHA256 для проверки подлинности
• Тайм-аут доставки -- 10 секунд на вебхук
• Доставка осуществляется по принципу "отправил и забыл" -- ошибка одного вебхука не блокирует остальные

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

Через панель управления

1. Перейдите в раздел Вебхуки в панели управления DocMap
2. Нажмите Создать вебхук
3. Введите URL вашего эндпоинта (в продакшене должен быть HTTPS)
4. Выберите события для подписки
5. Скопируйте секрет подписи немедленно -- он больше не будет показан

Через API

curl

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

TypeScript

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();

// Store this immediately -- it will never be shown again
console.log("Signing Secret:", data.secret);
console.log("Webhook ID:", data.webhook.id);

Python

import requests

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"]

# Store this immediately -- it will never be shown again
print("Signing Secret:", data["secret"])
print("Webhook ID:", data["webhook"]["id"])

WARNING

Секрет подписи возвращается только один раз при создании вебхука. Сохраните его в безопасном месте -- в переменной окружения или менеджере секретов.

Формат полезной нагрузки

При возникновении события DocMap отправляет POST-запрос на URL вашего вебхука со следующей структурой:

{
  "event": "extraction.completed",
  "data": {
    "id": "extract-abc123",
    "userId": "uid_xyz789",
    "templateId": "tpl_inv001",
    "templateName": "Standard Invoice",
    "fileName": "invoice-march.pdf",
    "status": "completed",
    "extractedData": {
      "vendor_name": "Acme Corp",
      "invoice_number": "INV-2024-003",
      "total_amount": 4750.00
    },
    "error": null,
    "variables": [...],
    "source": "api",
    "runId": null,
    "processingTimeMs": 3842,
    "createdAt": "2024-11-20T14:30:00.000Z"
  },
  "timestamp": "2024-11-20T14:30:04.000Z"
}

Заголовки

Каждый запрос вебхука включает следующие заголовки:

Заголовок	Описание
Content-Type	application/json
X-DocMap-Signature	Подпись HMAC-SHA256: sha256={hex_digest}
X-DocMap-Event	Название события (например, extraction.completed)

Проверка подписей

Всегда проверяйте заголовок X-DocMap-Signature, чтобы убедиться, что запрос пришел от DocMap. Подпись -- это HMAC-SHA256 хеш тела запроса с использованием вашего секрета подписи в качестве ключа.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto'

function verifyWebhookSignature(
  body: string,
  signature: string,
  secret: string,
): boolean {
  const expected = createHmac('sha256', secret)
    .update(body)
    .digest('hex')

  const received = signature.replace('sha256=', '')

  return timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(received, 'hex'),
  )
}

// Express example
app.post('/webhooks/docmap', (req, res) => {
  const signature = req.headers['x-docmap-signature'] as string
  const body = JSON.stringify(req.body)

  if (!verifyWebhookSignature(body, signature, process.env.DOCMAP_WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature')
  }

  const { event, data } = req.body

  console.log(`Received ${event} for extraction ${data.id}`)

  // Process the webhook...

  res.status(200).send('OK')
})

Python

import hmac
import hashlib

def verify_webhook_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256,
    ).hexdigest()

    received = signature.replace('sha256=', '')

    return hmac.compare_digest(expected, received)

# Flask example
from flask import Flask, request

app = Flask(__name__)

@app.post('/webhooks/docmap')
def handle_webhook():
    signature = request.headers.get('X-DocMap-Signature', '')
    body = request.get_data()

    if not verify_webhook_signature(body, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    payload = request.get_json()
    event = payload['event']
    data = payload['data']

    print(f"Received {event} for extraction {data['id']}")

    # Process the webhook...

    return 'OK', 200

TIP

Всегда используйте сравнение с постоянным временем (например, timingSafeEqual или hmac.compare_digest) для предотвращения атак по времени.

Справочник событий

Событие	Триггер
extraction.completed	Извлечение завершилось успешно. data.status равен "completed", а data.extractedData содержит результаты.
extraction.failed	Извлечение не удалось. data.status равен "failed", а data.error содержит сообщение об ошибке.

Лучшие практики

• Используйте HTTPS. Всегда используйте HTTPS-эндпоинт для URL вебхука. HTTP-эндпоинты могут быть отклонены в продакшене.

• Проверяйте подписи. Всегда проверяйте заголовок X-DocMap-Signature перед обработкой вебхука. Это подтверждает, что запрос пришел от DocMap и не был изменен.

• Отвечайте быстро. Возвращайте HTTP-статус 2xx в течение нескольких секунд. DocMap ждет ответа до 10 секунд. Если обработка занимает больше времени, подтвердите получение вебхука немедленно и обработайте его асинхронно.

• Обрабатывайте дубликаты. В редких случаях вебхук может быть доставлен более одного раза. Используйте id извлечения для дедупликации при необходимости.

• Храните секрет в безопасности. Храните секрет подписи в переменной окружения или менеджере секретов. Никогда не записывайте его непосредственно в исходный код и не коммитьте в систему контроля версий.

• Отслеживайте ошибки. Если ваш эндпоинт постоянно выдает ошибки, проверьте логи вашего сервера. DocMap логирует неудачные доставки, но не повторяет попытки.