Вебхуки

Вебхук отправляет события трекера на ваш сервер в момент их появления. Например, новую конверсию можно сразу передать в свою CRM, а алерт — в дежурный чат. Вкладка: Автоматизация → Вебхуки.

1. Добавить вебхук — URL, события и секрет. Открывает форму создания.

Создание

Поле	Что вводить
URL назначения	Публичный HTTPS-адрес вашего сервера. Локальные и приватные адреса блокируются.
События	Один или несколько пунктов из списка ниже.

Секрет генерирует система. Он показывается один раз сразу после создания. Скопируйте его сейчас. Если потеряли, нажмите «Сменить секрет»: старый секрет перестанет работать сразу.

События

Событие	Когда отправляется
Конверсия (conversion)	Создана или обновлена конверсия, например лид стал продажей.
Оффер отключён (offer_disabled)	Оффер выключен системой: провалы health-check или падение CR.
Домен забанен (domain_banned)	Домен заблокирован, трафик переведён на другой домен.
Сработал алерт (alert_fired)	Сработало правило алерта.

Событие «Клик» не отправляется

В API можно указать событие click, но трекер его не генерирует. В интерфейсе этого пункта нет.

Формат запроса

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-Webhook-Event: conversion
X-Webhook-Signature: 3f9a…c1d2

{"event":"conversion","data":{...},"timestamp":"2026-10-13T09:15:00.000Z"}

Поля data по событиям:

• conversion: conversionId, status, payout, currency, clickToken, offerId, isNew.
• offer_disabled: offerId, name, reason, source (health_check или cr_threshold).
• domain_banned: domainId, domain, reason, rotatedTo.
• alert_fired: ruleName, metric, operator, threshold, value, sampleSize, scope, dimensionValue, action, firedAt.

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

X-Webhook-Signature — это HMAC-SHA256 от сырого тела запроса вашим секретом, в hex-виде, без префикса.

Важно: считайте подпись от тела в том виде, в котором оно пришло, а не от JSON, который вы распарсили и собрали заново. Пробелы и порядок ключей меняют подпись.

Node.js

import crypto from 'node:crypto';
import express from 'express';

const SECRET = process.env.TG_WEBHOOK_SECRET;
const app = express();

// Нужно сырое тело, поэтому express.raw, а не express.json.
app.post('/telegfy', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  const received = req.get('X-Webhook-Signature') ?? '';
  const ok =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body.toString('utf8'));
  // идемпотентная обработка: см. раздел «Повторы» ниже
  res.status(200).end();
});

Python

import hmac, hashlib, json
from flask import Flask, request, abort

SECRET = b"ваш-секрет"
app = Flask(__name__)

@app.post("/telegfy")
def telegfy():
    raw = request.get_data()  # сырое тело, без парсинга
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Webhook-Signature", "")
    if not hmac.compare_digest(received, expected):
        abort(401)
    event = json.loads(raw)
    return "", 200

Доставка и повторы

• Запрос считается доставленным, если ваш сервер ответил 2xx за 5 секунд.
• Иначе повтор через 1, 5, 15 и 60 минут. Всего 5 попыток, после этого доставка помечается как неуспешная.
• Повторы могут прийти после ответа, который вы уже обработали из-за сетевой ошибки. Поэтому обрабатывайте события идемпотентно: например, ключ event + conversionId или event + ruleName + firedAt.

Права

Создавать, менять и удалять вебхуки могут владелец, администратор и редактор. Наблюдатель видит список.

API

/api/v1/webhooks — только с сессией (JWT). Ключи API сюда не допускаются. Секрет при создании и при смене возвращается один раз.

Связанное

• Правила алертов — что вызывает alert_fired.
• Каналы уведомлений — другой способ получать алерты, без подписи.