Webhooks API
Получайте HTTP-уведомления в реальном времени при каждом просмотре документа. Интегрируйте с CRM, автоматизируйте follow-up, стройте аналитику.
Обзор
Когда получатель открывает ваш документ по ссылке, DocWatch отправляетPOST запрос на настроенный URL с информацией о просмотре.
POST https://your-server.com/webhook/docwatch Content-Type: application/json X-DocWatch-Event: document.viewed X-DocWatch-Signature: sha256=a1b2c3d4...
Настройка
Откройте Профиль в DocWatch
В секции Webhook (CRM-интеграция) вставьте URL вашего эндпоинта
Нажмите Сохранить. Signing Secret сгенерируется автоматически.
Скопируйте Signing Secret — используйте для проверки подписи на вашей стороне
События
document.viewedВызывается при каждом просмотре документа через ссылку. Включает данные о просмотрщике, документе и кастомных полях.
Дополнительные события (document.downloaded, page.viewed) будут добавлены в следующих версиях.
Формат данных
{
"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Тип события
timestamprequiredВремя отправки уведомления
data.documentIdrequiredУникальный ID документа в DocWatch
data.documentNamerequiredНазвание файла
data.linkSlugrequiredSlug ссылки, через которую открыли документ
data.viewIdrequiredУникальный ID просмотра
data.viewerEmailEmail просмотрщика. null если email-гейт выключен
data.viewerIpIP-адрес просмотрщика
data.customFieldsОтветы на кастомные поля (имя, компания и т.д.)
data.viewedAtrequiredВремя открытия документа
Проверка подписи
Каждый запрос подписан HMAC-SHA256 с вашим Signing Secret. Заголовок X-DocWatch-Signature содержит подпись в формате sha256=hex_digest.
Алгоритм проверки:
- 1. Получите raw body запроса (не парсите JSON до проверки)
- 2. Вычислите
sha256=+HMAC-SHA256(secret, body) - 3. Сравните с заголовком
X-DocWatch-Signatureчерез timing-safe compare - 4. Если не совпадает — вернуть 401
Примеры кода
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);
});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
$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
Безопасность
- Всегда проверяйте подпись
X-DocWatch-Signature - Используйте HTTPS для вашего endpoint
- Не логируйте Signing Secret в открытом виде
- Если secret скомпрометирован — удалите webhook URL и сохраните заново, secret пересоздастся
Вопросы по интеграции: info@apx-digital.ru