DocWatchDocWatch
WEBHOOKSv1

Webhooks API

Получайте HTTP-уведомления в реальном времени при каждом просмотре документа. Интегрируйте с CRM, автоматизируйте follow-up, стройте аналитику.

Обзор

Когда получатель открывает ваш документ по ссылке, DocWatch отправляетPOST запрос на настроенный URL с информацией о просмотре.

Endpoint
POST https://your-server.com/webhook/docwatch
Content-Type: application/json
X-DocWatch-Event: document.viewed
X-DocWatch-Signature: sha256=a1b2c3d4...

Настройка

1

Откройте Профиль в DocWatch

2

В секции Webhook (CRM-интеграция) вставьте URL вашего эндпоинта

3

Нажмите Сохранить. Signing Secret сгенерируется автоматически.

4

Скопируйте Signing Secret — используйте для проверки подписи на вашей стороне

События

ACTIVEdocument.viewed

Вызывается при каждом просмотре документа через ссылку. Включает данные о просмотрщике, документе и кастомных полях.

Дополнительные события (document.downloaded, page.viewed) будут добавлены в следующих версиях.

Формат данных

document.viewed payload
{
  "event": "document.viewed",
  "timestamp": "2026-04-10T15:30:00.000Z",
  "data": {
    "documentId": "clx1abc2d3ef4",
    "documentName": "КП для BigCorp.pdf",
    "linkSlug": "xK9mP2",
    "viewId": "clx5xyz6789",
    "viewerEmail": "ivanov@bigcorp.ru",
    "viewerIp": "185.23.45.67",
    "customFields": {
      "name": "Иванов Пётр",
      "company": "BigCorp"
    },
    "viewedAt": "2026-04-10T15:30:00.000Z"
  }
}

Параметры

eventrequired
string

Тип события

timestamprequired
ISO 8601

Время отправки уведомления

data.documentIdrequired
string

Уникальный ID документа в DocWatch

data.documentNamerequired
string

Название файла

data.linkSlugrequired
string

Slug ссылки, через которую открыли документ

data.viewIdrequired
string

Уникальный ID просмотра

data.viewerEmail
string | null

Email просмотрщика. null если email-гейт выключен

data.viewerIp
string

IP-адрес просмотрщика

data.customFields
object | null

Ответы на кастомные поля (имя, компания и т.д.)

data.viewedAtrequired
ISO 8601

Время открытия документа

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

Каждый запрос подписан HMAC-SHA256 с вашим Signing Secret. Заголовок X-DocWatch-Signature содержит подпись в формате sha256=hex_digest.

Алгоритм проверки:

  1. 1. Получите raw body запроса (не парсите JSON до проверки)
  2. 2. Вычислите sha256= + HMAC-SHA256(secret, body)
  3. 3. Сравните с заголовком X-DocWatch-Signature через timing-safe compare
  4. 4. Если не совпадает — вернуть 401

Примеры кода

Node.js (Express)
const crypto = require('crypto');

function verify(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

app.post('/webhook/docwatch', express.text({ type: '*/*' }), (req, res) => {
  const sig = req.headers['x-docwatch-signature'];
  if (!verify(req.body, sig, process.env.DOCWATCH_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  console.log('Viewed:', event.data.documentName);
  console.log('By:', event.data.viewerEmail);
  res.sendStatus(200);
});
Python (Flask)
import hmac, hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.route('/webhook/docwatch', methods=['POST'])
def webhook():
    sig = request.headers.get('X-DocWatch-Signature', '')
    if not verify(request.data, sig, DOCWATCH_SECRET):
        return 'Invalid signature', 401

    event = request.json
    print(f"Viewed: {event['data']['documentName']}")
    print(f"By: {event['data']['viewerEmail']}")
    return '', 200
PHP
<?php
$body = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_DOCWATCH_SIGNATURE'] ?? '';
$secret = getenv('DOCWATCH_SECRET');

$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($body, true);
error_log("Viewed: " . $event['data']['documentName']);
error_log("By: " . $event['data']['viewerEmail']);
http_response_code(200);

Интеграция с CRM

amoCRM

Настройки → Интеграции → Входящие Webhooks → скопируйте URL → вставьте в DocWatch. При просмотре документа в сделке появится примечание.

Bitrix24

Автоматизация → Вебхуки → Входящий → скопируйте URL → вставьте в DocWatch.

Zapier / Make

Создайте Zap/Scenario с триггером «Webhooks by Zapier» (Catch Hook) → скопируйте URL → вставьте в DocWatch. Далее настройте действие: задача в CRM, Slack, Google Sheets и т.д.

Ошибки и retry

Timeout10 секунд. Если ваш сервер не ответил — запрос отменяется.
RetryНет. Один запрос, без повторов. Для гарантированной доставки используйте Zapier/Make как промежуточный слой.
2xxЛюбой 2xx-ответ считается успешной доставкой.

Безопасность

  • Всегда проверяйте подпись X-DocWatch-Signature
  • Используйте HTTPS для вашего endpoint
  • Не логируйте Signing Secret в открытом виде
  • Если secret скомпрометирован — удалите webhook URL и сохраните заново, secret пересоздастся

Вопросы по интеграции: info@apx-digital.ru