🕸️ Facebook Pixel Postback ("Веб-хуки")
Это старый механизм, ему много лет. Мы его не развиваем и в одном из ближайших релизов отключим совсем. Не стройте на нём новые интеграции: всё, что вы соберёте сейчас, придётся переделывать.
Взамен готовятся новые веб-хуки. Они уже работают — на них построена наша интеграция с некоторыми крупными партнёрами, — и скоро они будут доступны для всех авторов публично. Коротко, чем они лучше: события приходят в JSON; гарантированная дедупликация в формате близком к Stripe; типов событий почти сорок вместо шести, и вы подписываетесь только на нужные; у каждой точки свой адрес для получения уведомлений, свой секрет и свой список проектов, так что точек может быть несколько; каждый запрос подписан, и подпись можно проверить; историю доставок прозрачно видно в ЛК, а неудачную доставку можно запустить заново при желании.
Как только новые веб-хуки откроются для всех, здесь появится ссылка на их описание и понятная дата когда старые будут удалены. Пока этого не произошло, страница ниже описывает то, что работает сегодня.
Получайте нотификации на ваш URL о событиях по проекту.
Чтобы настроить, перейдите в Настройки проекта в раздел Веб-хуки. Адрес один на проект.
После того как вы укажете ссылку для получения нотификаций, вы сможете отправить тестовые запросы, которые помогут вам в настройке на своей стороне.
Передаваемые параметры
На ваш URL уходит запрос POST с телом в формате application/x-www-form-urlencoded — то есть обычная HTML-форма, а не JSON. Параметры такие:
| Параметр | Тип | Описание |
|---|---|---|
| clickid | string | ID перехода. Если его нет, то передается пустое значение. |
| paymentId | string | ID платежа. Передается для событий с типами firstbill, rebill, refund. Если его нет, то передается пустое значение. |
| type | string | Тип события. Может быть trial, firstbill, rebill, refund, cancel или update. |
| plan | int | ID тарифа. |
| planName | string | Название тарифа. |
| planPrice | string | Сумма оплаты в копейках или центах. |
| planCurrency | string | Валюта тарифа. Может быть RUB, USD или EUR. |
| planPeriod | string | Период оплаты тарифа: 1 month, 3 months, 6 months, 1 year.Для разового тарифа — One-time.Для старых тарифов возможны 1 day, 3 days, 1 week, 2 weeks, 2 months. |
| trialPeriod | string | Срок пробного периода тарифа — число дней и слово days, например 7 days. Если пробного периода нет, то передается пустое значение. |
| nextPayment | string | Расчетная дата следующего платежа по подписке. Если даты нет, то передается пустое значение. |
| kickAt | string | Расчетная дата до которой оплачена подписка. Если даты нет, то передается пустое значение. |
| subscription | string | ID подписки. |
| consumer | int | ID пользователя. Если его нет, то передается пустое значение. |
| consumerEmail | string | Email пользователя. Если его нет, то передается пустое значение. |
| consumerTelegramId | string | Telegram ID пользователя. Если его нет, то передается пустое значение. |
| txid | string | Хеш платежа или подписки, по которым пришло событие. |
txid не годится для дедупликации
У двух разных событий по одной и той же подписке txid будет одинаковый. Различайте события по паре type + paymentId или type + subscription.
Типы событий
trial— новая подписка с пробным периодом.firstbill— новая подписка.update— обновление данных о подписке (отправляется когда нам становится известенconsumerTelegramIdпосле перехода пользователя в бота).rebill— продление подписки.cancel— отмена подписки.refund— возврат платежа.
Покупка цифрового продукта не генерирует события. Запрос по продукту придёт только на возврат или на update, и вместо полей plan* в нём будут product, productName, productPrice и productCurrency, а полей subscription, trialPeriod, nextPayment и kickAt не будет вовсе. Отдельного события об успешной покупке продукта в старых веб-хуках нет и не появится — оно есть в новых.
clickId
Вы можете самостоятельно размечать подписки с помощью параметра clickId. Для этого добавьте к платежной ссылке вашего проекта ?clickId=[значение]
Пример: https://paywall.pw/sampleproject?clickId=123456
Значение не может превышать 34 символа и должно состоять из цифр и латинских букв. Значение, которое в это не укладывается, мы молча отбрасываем — ошибки не будет, просто в clickid приедет пустая строка.
Если пользователь перейдет по ссылке с параметром и совершит подписку, то у его подписки сохранится значение clickId. При отправке запроса на ваш URL это значение будет передаваться с остальными сведениями о подписке.
Генерируйте уникальные значения для каждого перехода. Это может пригодиться при реализации собственной партнерской (реферальной) программы.
Отправка запросов
Первый запрос отправляется сразу. Если он не удался, мы делаем ещё несколько попыток через разные интервалы времени. В сумме попытки растягиваются примерно на 18 дней, после чего событие теряется навсегда. Повторяем не всегда – ответ 2xx считается успехом, повторять будем при ответах 5xx и 429, ответьте любым другим кодом из 4xx и событие более не будет переотправлено.