SupportCandy Webhooks - Плагин WordPress

Руководство по настройке SupportCandy Webhooks для автоматизации поддержки

SupportCandy Webhooks нужен не для украшения формы тикета, а для связки службы поддержки с внешними системами: CRM, таблицами, чатами, собственным приложением, аналитикой инцидентов или внутренним маршрутизатором задач. В этом руководстве разберём, как спланировать вебхуки, какие события выбирать, как настроить безопасную доставку, как проверить входящий запрос и что делать, если уведомление не дошло до получателя.

Материал рассчитан на владельца WordPress-сайта, администратора поддержки и разработчика, которому нужно получить данные из SupportCandy без ручного экспорта. Здесь не будет инструкций по покупке, регистрации лицензии или обходу ограничений. Мы считаем, что базовый SupportCandy уже работает, а задача - аккуратно подключить событие тикета к внешнему рабочему процессу.

Главная идея простая: вебхук отправляет HTTP-запрос на указанный адрес, когда в системе поддержки происходит выбранное событие. Но практическая ценность появляется только после правильной схемы: какой триггер выбран, какие данные принимает внешняя сторона, как проверяется подпись, где смотреть логи и как не превратить каждый ответ агента в шум для всей команды.

Где вебхуки действительно помогают службе поддержки

Вебхук полезен там, где обычного письма или просмотра списка тикетов недостаточно. Email-уведомление хорошо работает для человека, но плохо подходит для автоматической обработки: его нужно парсить, учитывать пересылки, вложения, подписи и разные шаблоны писем. Вебхук отправляет структурированный запрос на заранее подготовленный адрес, поэтому внешняя система может сразу решить, что делать с событием.

У SupportCandy Webhooks есть несколько подтверждённых триггеров: создание тикета, изменение статуса, смена исполнителя, закрытие, ответ в тикете, приватная заметка, изменение темы, категории, приоритета, ticket fields, agent-only fields и событие Out of SLA. Из этого набора видно, что продукт ориентирован не только на "новый тикет", но и на весь жизненный цикл обращения. Именно поэтому его лучше воспринимать как мост между helpdesk и внешними процессами, а не как ещё один канал уведомлений.

Типичные рабочие сценарии:

• Отправить новый тикет в CRM или внутренний реестр обращений, чтобы у менеджера был единый профиль клиента.
• Сообщить в канал поддержки, когда тикет стал срочным, поменял приоритет или вышел за SLA.
• Передать закрытие тикета в систему аналитики, чтобы считать скорость реакции и повторные обращения.
• Синхронизировать внутреннее поле агента с внешним инструментом контроля качества, не показывая это поле клиенту.
• Запустить собственный обработчик, который проверяет подпись, фильтрует событие и уже потом отправляет данные дальше.

Самый сильный сценарий для SupportCandy Webhooks - не массовая отправка всего подряд, а точечная автоматизация вокруг важных изменений тикета. Если событие должен увидеть человек прямо сейчас, возможно, хватит email или Slack-интеграции. Если событие должно попасть в базу, очередь, отчёт, внешний API или отдельную бизнес-логику, вебхук обычно удобнее.

Кому продукт подойдёт

Плагин хорошо подходит сайтам, где SupportCandy уже стал основным местом общения с клиентами, но поддержка не живёт только внутри WordPress. Это интернет-магазины, SaaS-проекты, агентства, образовательные сайты, сервисные компании, внутренние порталы и любые команды, которым нужно связывать тикеты с внешним контекстом. Польза особенно заметна, когда у обращения есть следующий шаг вне WordPress: создать задачу, обновить карточку клиента, записать событие в журнал, запустить проверку SLA, отправить сигнал дежурному инженеру.

Также SupportCandy Webhooks будет полезен разработчику, которому нужен контролируемый исходящий канал. В отличие от ручной интеграции через произвольные хуки WordPress, здесь администратор управляет адресом доставки и списком событий из интерфейса плагина. Это проще сопровождать: можно отключить конкретный вебхук, изменить URL, обновить секрет и проверить логи без правки кода сайта.

Кому стоит выбрать другой подход

Если нужно построить многошаговую автоматизацию "если произошло А и Б, подожди, проверь условие, затем выполни несколько действий", вебхука может быть мало. В таком случае смотрите в сторону Workflow/Automations внутри SupportCandy, внешних автоматизаторов или отдельного сервиса обработки событий. Если нужен только человекочитаемый сигнал о новом обращении, проще настроить email-уведомление или специализированную интеграцию, например Slack, где уже есть сценарий ответа из треда.

Ещё один важный случай - нет принимающей стороны. SupportCandy Webhooks отправляет запрос, но он не заменяет сервер, который этот запрос примет, проверит и обработает. Если у вас нет внешнего endpoint, CRM-вебхука, automation-сервиса или собственного скрипта, сначала подготовьте получателя. Для тестов подойдёт временный сервис приёма вебхуков, но для рабочих данных лучше использовать контролируемую инфраструктуру.

Что проверить перед установкой и первым запуском

Перед настройкой вебхуков проверьте не только наличие самого расширения, но и готовность всей цепочки. Ошибки часто возникают не из-за SupportCandy, а из-за принимающего URL, блокировки исходящих запросов, неверного секрета, изменения payload перед проверкой подписи или слишком широкого выбора триггеров.

Базовая готовность сайта

SupportCandy должен быть установлен, активирован и настроен настолько, чтобы на сайте реально создавались тикеты, назначались агенты, менялись статусы и работали нужные поля. Если базовый helpdesk ещё не проверен, вебхук будет сложнее диагностировать: вы не поймёте, проблема в событии, в настройке тикета или в доставке запроса.

Для WordPress-плагинов такого типа особенно важны права доступа. Триггер "изменение исполнителя" бесполезен, если на сайте ещё не созданы агенты и роли. Триггеры по ticket fields и agent-only fields требуют, чтобы соответствующие поля существовали и реально менялись в карточке тикета. Событие Out of SLA имеет смысл только там, где настроена логика SLA. Не включайте всё заранее "на будущее": сначала добейтесь предсказуемого поведения базовой функции.

Готовность принимающего URL

Delivery URL должен быть доступен снаружи, принимать HTTP-запросы, не требовать интерактивной авторизации и быстро отвечать. Если внешняя система медленно обрабатывает данные, лучше принимать запрос, сохранять его в очередь и отвечать успешно, а сложную работу выполнять отдельно. Так вебхук не будет зависеть от тяжёлой операции.

Для проверки используйте временный тестовый адрес, который показывает headers, тело запроса и код ответа. Это помогает увидеть фактическую структуру payload, убедиться, что выбранный триггер сработал, и понять, какой header приходит с подписью. Но не оставляйте временный сервис в рабочих настройках: в запросе могут оказаться данные клиента, тема обращения, email, внутренние поля или фрагменты переписки.

Практическая проверка: до подключения CRM или собственного обработчика создайте отдельный тестовый вебхук с безопасным endpoint, выполните одно действие в тестовом тикете и убедитесь, что видите запрос, headers, тело и статус ответа.

Безопасность, доступы и данные клиента

Вебхуки часто передают данные, которые не стоит показывать лишним системам. Поэтому заранее решите, какие события действительно нужны внешнему получателю. Например, событие приватной заметки может быть полезно для внутреннего контроля качества, но может быть лишним для CRM. Изменение agent-only fields может содержать служебные данные, которые не предназначены клиенту и не должны попадать в публичные каналы.

Если вы добавляете secret key, принимающая сторона должна проверять подпись. В документации SupportCandy указано, что подпись приходит в HTTP header X-WPSC-Webhook-Signature как base64-кодированный HMAC-SHA256 от payload. Это важнее, чем кажется: без проверки подписи любой внешний отправитель теоретически может попробовать имитировать запрос на ваш endpoint.

Также проверьте, кто в команде имеет право менять вебхуки. Адрес доставки, secret key и набор событий - это не косметические настройки. Ошибка в них может отправить данные не туда, остановить автоматизацию или создать дубль событий.

Установка и первичная проверка расширения

Базовый SupportCandy можно установить из каталога WordPress или загрузить вручную через раздел плагинов. Само расширение Webhooks относится к дополнительным модулям SupportCandy, поэтому в админке должен быть установлен основной плагин и активирован соответствующий add-on. Точные названия экранов могут отличаться в зависимости от набора расширений, но рабочая логика остаётся одинаковой: сначала основной helpdesk, затем Webhooks, затем настройка конкретного endpoint.

Последовательность после активации

1. Убедитесь, что базовый раздел SupportCandy доступен в админ-панели WordPress.
2. Откройте настройки SupportCandy и найдите раздел Webhooks.
3. Создайте отдельный тестовый тикет, чтобы не использовать реальные обращения клиентов.
4. Подготовьте временный или внутренний endpoint, который покажет входящий запрос.
5. Создайте первый вебхук только с одним триггером, например создание тикета.
6. Сохраните настройку, выполните действие в тестовом тикете и откройте лог доставки.

Не начинайте с пяти разных триггеров и рабочей CRM. Если запрос не придёт, придётся одновременно проверять событие, URL, firewall, формат payload, права, SSL, подпись и обработку на стороне получателя. Один простой триггер с тестовым тикетом резко сокращает диагностику.

Первый критерий успеха

Первый успешный запуск - это не "вебхук создан". Успехом можно считать только цепочку: событие произошло в SupportCandy, исходящий запрос появился на получателе, в логах виден корректный ответ, payload содержит ожидаемые данные, а принимающая сторона может отличить тест от рабочего обращения. Если вы не проверили payload, вы не знаете, какие поля реально доступны для следующей интеграции.

На этом этапе стоит завести простую таблицу сценариев: триггер, действие в тестовом тикете, ожидаемый запрос, ожидаемый ответ, что делать дальше. Такая таблица пригодится не только при настройке, но и после обновлений, когда нужно быстро убедиться, что интеграция не сломалась.

Подробная настройка: имя, Delivery URL, триггеры и секрет

Раздел настройки вебхука состоит из нескольких простых полей, но каждое из них влияет на поддержку в продакшене. Ошибка в названии создаёт хаос в списке, ошибка в URL ломает доставку, слишком широкий набор триггеров создаёт лишний шум, а отсутствие секрета усложняет безопасную обработку. Ниже - практический порядок, который помогает настроить вебхук так, чтобы его можно было сопровождать через несколько месяцев.

Webhook Name: называйте по событию и получателю

Название вебхука должно объяснять не только событие, но и адресата. Плохое имя: Test, CRM, Webhook 1. Хорошее имя: New ticket to CRM staging, High priority ticket to incident router, Closed ticket to support analytics. Когда в списке появится несколько интеграций, такие имена помогут быстро понять, что можно отключить без риска.

Если у вас есть тестовый и рабочий endpoint, не смешивайте их в одном вебхуке. Создайте отдельные записи и явно отметьте среду. Это уменьшит риск, что тестовые тикеты попадут в рабочую CRM или рабочие обращения уйдут в временный приёмник.

Delivery URL: проверяйте доступность и стабильность

В поле Delivery URL укажите адрес, куда SupportCandy будет отправлять запросы. Для рабочих данных используйте HTTPS. Убедитесь, что endpoint не отдаёт редирект на страницу входа, не блокирует запросы по user agent и не требует cookie-сессию администратора. Вебхук должен быть машинным входом, а не страницей админки.

Если внешняя система поддерживает разные endpoint для теста и продакшена, начните с тестового. После проверки перенесите настройку в рабочий URL и снова выполните контрольное событие. Не полагайтесь на то, что "у тестового и рабочего адреса всё одинаково": разные домены, сертификаты, правила firewall и ограничения payload могут вести себя по-разному.

Triggers: выбирайте событие под бизнес-смысл

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

После выбора триггеров задайте себе вопрос: "Что будет, если это событие произойдёт десять раз за минуту?" Если внешняя система начнёт создавать дубли, спамить канал или переписывать одно и то же поле, нужна дополнительная фильтрация на принимающей стороне.

Secret Key: включайте там, где данные обрабатываются автоматически

Secret key в настройке вебхука нужен для проверки подлинности запроса. SupportCandy формирует подпись от payload и передаёт её в header X-WPSC-Webhook-Signature. Принимающая сторона должна вычислить подпись с тем же секретом и сравнить результат. Если подпись не совпадает, запрос лучше отклонить и не выполнять бизнес-действия.

Не храните секрет в публичном репозитории, теме WordPress или коде, который видит клиент. Держите его в переменных окружения, секретах сервера, настройках защищённого приложения или другом безопасном хранилище. При подозрении на утечку замените secret key в SupportCandy и в принимающем обработчике одновременно.

Минимальный пример проверки подписи на PHP

Этот фрагмент нужен только на принимающей стороне, а не внутри SupportCandy. Он показывает сам принцип проверки: взять raw payload, вычислить HMAC-SHA256 с тем же секретом и сравнить с header. В реальном проекте добавьте журналирование, проверку метода запроса и аккуратную обработку ошибок.

<?php
$payload = file_get_contents('php://input');
$secret = getenv('SUPPORTCANDY_WEBHOOK_SECRET');
$received = $_SERVER['HTTP_X_WPSC_WEBHOOK_SIGNATURE'] ?? '';

$expected = base64_encode(
    hash_hmac('sha256', $payload, wp_specialchars_decode($secret, ENT_QUOTES), true)
);

if (!$secret || !$received || !hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid webhook signature');
}

http_response_code(200);
echo 'OK';

Проверка после внедрения простая: отправьте тестовое событие с правильным секретом, затем временно измените секрет на стороне обработчика и убедитесь, что запрос отклоняется. После теста верните правильное значение. Такой контроль показывает, что endpoint не просто принимает любой POST-запрос, а действительно проверяет источник.

Как устроить цепочку "тикет - вебхук - внешняя система"

Вебхук сам по себе не является полноценной интеграцией. Это доставка события. Интеграция начинается, когда принимающая сторона понимает payload, проверяет подпись, сохраняет идентификатор события и выполняет действие без дублей. Для SupportCandy это особенно важно, потому что одно обращение может жить долго: клиент ответил, агент добавил заметку, статус изменился, приоритет поднялся, тикет закрылся. Если каждое событие без фильтрации создаёт новую запись, внешняя система быстро превращается в мусорный журнал.

Минимальная архитектура обработчика

Даже маленький обработчик стоит проектировать в четыре слоя:

1. Приём запроса: проверить метод, размер тела, content type и базовую доступность.
2. Безопасность: проверить X-WPSC-Webhook-Signature, отклонить запрос без корректной подписи.
3. Нормализация: разобрать payload, выделить ID тикета, тип события, статус, приоритет, исполнителя и нужные поля.
4. Действие: обновить существующую запись, создать задачу, отправить уведомление или поставить событие в очередь.

Если внешняя система поддерживает upsert, используйте ID тикета как стабильный ключ. Тогда изменение статуса не создаст вторую карточку, а обновит существующую. Если payload содержит разные поля для разных событий, обработчик должен быть терпимым: отсутствие необязательного поля не должно ломать весь процесс.

Почему лучше не отправлять всё сразу в конечный сервис

Можно указать Delivery URL внешнего сервиса напрямую, например URL автоматизатора или CRM. Это быстро, но не всегда гибко. Промежуточный обработчик даёт больше контроля: он проверяет подпись, убирает лишние данные, скрывает внутренние поля, мапит названия статусов, защищает от дублей и пишет собственный журнал. Такой слой особенно полезен, если в SupportCandy есть персональные данные, agent-only fields или разные получатели для разных категорий тикетов.

Для маленькой команды можно начать с прямого endpoint, но заранее фиксируйте ограничения. Если появятся дубли, частые изменения статуса, требования безопасности или сложная маршрутизация, лучше вынести обработку в отдельный сервис.

Триггеры тикетов: как не создать шум и дубли

Поддержка живёт в событиях, но не каждое событие достойно внешней автоматизации. При настройке SupportCandy Webhooks полезно разделить триггеры на три группы: стартовые, процессные и контрольные. Такое деление помогает выбрать минимальный набор и не перегрузить внешнюю систему.

Стартовые события

Create Ticket обычно самый понятный триггер. Он создаёт начальную точку для внешней записи: новый лид поддержки, новая строка в отчёте, новая задача в системе контроля инцидентов. Для него важно сохранить исходный ID тикета, тему, категорию, приоритет, автора и URL карточки, если он есть в payload или может быть сформирован обработчиком. Без стабильного ID следующая синхронизация станет ненадёжной.

Если на сайте включены guest tickets, отдельно проверьте, какие данные доступны для гостевого клиента. Не предполагайте, что payload всегда будет одинаковым для зарегистрированных пользователей и гостей. Тестируйте оба сценария, если оба разрешены на вашем сайте.

Процессные события

Change Status, Change Assignee, Reply to Ticket, Change Ticket Priority и похожие события помогают держать внешнюю систему в актуальном состоянии. Но они же чаще всего создают шум. Например, если агент меняет статус после каждого ответа, внешний канал может получить десятки уведомлений по одному обращению.

Решение - фильтровать событие по смыслу. Не каждое изменение статуса должно уходить в Slack или CRM. Можно принимать все события в свой endpoint, но дальше отправлять только важные: переход в "High", назначение на конкретную группу, просрочка SLA, закрытие после решения или ответ клиента в тикете с критичным приоритетом.

Контрольные события

Out of SLA и события по agent-only fields часто важнее обычных ответов. Они отражают внутреннее состояние поддержки: просрочка, эскалация, техническая классификация, ручное решение агента. Такие события нужно проектировать осторожно. Если agent-only field содержит внутренний диагноз, его не стоит отправлять в публичную таблицу. Если Out of SLA должен поднять инцидент, убедитесь, что SLA-правило срабатывает один раз или внешний обработчик умеет подавлять повтор.

Правило настройки: начинайте с одного стартового триггера и одного контрольного триггера, затем добавляйте процессные события только после анализа реального потока тикетов.

Agent-only fields, ticket fields и приватные заметки в интеграциях

SupportCandy позволяет работать не только с базовыми полями тикета. Ticket fields расширяют сам тикет и могут отображаться пользователю в зависимости от настроек видимости. Agent-only fields похожи по назначению, но рассчитаны на внутренние данные команды, хотя документация отдельно предупреждает: если добавить их в customer ticket list items, клиент может увидеть такие поля в списке. Это важный нюанс для вебхуков, потому что "внутреннее поле" не всегда автоматически означает "никогда не выходит наружу".

Что отправлять во внешние системы

Если интеграция нужна CRM, ей обычно достаточно ID тикета, контакта, темы, категории, статуса и итоговой классификации. Если интеграция нужна внутренней аналитике, можно передавать больше: приоритет, agent-only классификацию, время реакции, закрывающий статус. Если получатель - публичный чат или канал продаж, передавайте минимум и избегайте приватных заметок.

Перед включением триггеров Submit Private Note и Change Agentonly Fields пройдите маленький аудит:

• Какие поля могут содержать персональные данные, внутреннюю оценку клиента или технические секреты.
• Кто имеет доступ к внешней системе, куда уйдёт запрос.
• Нужно ли маскировать email, телефон, внутренние комментарии или прикреплённые ссылки.
• Можно ли заменить подробный payload коротким событием: "требуется эскалация", "ожидает инженера", "закрыто после проверки".

Как использовать поля без утечки лишней информации

Безопасная стратегия - отправлять во внешний endpoint полный запрос, но не пересылать его дальше как есть. Обработчик должен выбрать только нужные значения. Например, в CRM можно передать категорию и номер тикета, а private note оставить только в защищённом внутреннем журнале. В канал дежурных можно отправить статус, приоритет и ссылку на тикет, но не весь текст переписки.

Если внешняя система не позволяет гибко фильтровать данные, лучше создать промежуточный обработчик. Он будет принимать webhook от SupportCandy, проверять подпись, очищать payload и формировать безопасное сообщение. Это не усложнение ради архитектуры, а практическая защита от случайной публикации внутренних данных.

Практический пример: отправляем критичные тикеты в внешний обработчик

Разберём сценарий, который часто нужен технической поддержке: новый тикет или изменение приоритета должны попадать во внешний обработчик, а обработчик уже решает, создавать ли инцидент, уведомлять дежурного или просто обновлять CRM. Мы не будем привязываться к конкретному SaaS, потому что у разных команд разные инструменты. Важно понять цепочку и проверки.

Цель

Нужно получить управляемую интеграцию: SupportCandy отправляет событие, endpoint проверяет подпись, находит ID тикета и приоритет, затем записывает событие в журнал и отправляет дальше только критичные обращения. В результате команда видит не все ответы подряд, а только важные сигналы.

Подготовка

• В SupportCandy есть тестовый тикет, категории и приоритеты.
• Включён Webhooks add-on и доступен раздел Webhooks.
• Есть тестовый endpoint, который показывает входящие headers и тело запроса.
• Для рабочего endpoint подготовлен secret key и лог ошибок.
• Команда договорилась, какие статусы и приоритеты считаются критичными.

Шаги настройки

1. Откройте настройки SupportCandy и перейдите в раздел Webhooks.
2. Нажмите Add New и задайте понятное имя, например Critical ticket events to incident router.
3. В поле Delivery URL укажите тестовый endpoint, а не сразу рабочий адрес.
4. Выберите триггер Create Ticket и сохраните вебхук.
5. Создайте тестовый тикет с безопасными демонстрационными данными.
6. Проверьте, что endpoint получил запрос, а в логах SupportCandy есть запись доставки.
7. Добавьте Change Ticket Priority, измените приоритет тестового тикета и снова проверьте payload.
8. Добавьте secret key, обновите принимающий endpoint и проверьте header X-WPSC-Webhook-Signature.
9. Перенесите Delivery URL на рабочий endpoint и повторите один контрольный тест.

Что должно получиться

После настройки новый тикет создаёт исходящий запрос, изменение приоритета создаёт отдельное событие, а принимающая сторона видит подпись, payload и может сопоставить событие с конкретным ID тикета. Если endpoint фильтрует по приоритету, в итоговую систему уходят только обращения, которые действительно требуют внимания.

Нюанс, который часто мешает

Если вы меняете приоритет автоматически через workflow или другим расширением, событие может срабатывать без ручного действия агента. Это нормально, но требует защиты от дублей. Обработчик должен понимать, что тикет уже был отправлен как критичный, и не создавать новый инцидент при каждом повторном сохранении.

План внедрения на тестовом сайте перед продакшеном

Вебхуки лучше внедрять не как разовую настройку, а как маленький проект. Это не бюрократия: SupportCandy Webhooks соединяет реальные обращения клиентов с внешними системами, поэтому ошибка может быстро размножиться. Один неверный триггер создаст десятки дублей, один открытый endpoint примет чужой запрос, один слишком широкий payload отправит приватную заметку туда, где её не должны видеть.

Ниже - практичный план внедрения, который подходит для сайта без отдельной команды разработчиков. Его можно выполнить на staging-копии, закрытом тестовом сайте или на рабочем сайте с безопасными демонстрационными тикетами, если staging нет. Главное - не начинать с реальных клиентских обращений и не подключать сразу конечную CRM без промежуточной проверки.

Этап "карта событий"

Сначала выпишите, какие события вам действительно нужны. Не используйте список триггеров как список задач. У каждого события должен быть получатель, действие и критерий успеха. Например: Create Ticket создаёт запись в CRM, Change Ticket Priority обновляет поле важности, Out of SLA создаёт внутренний инцидент. Если для триггера нельзя сформулировать действие, его пока не включайте.

Для каждого события укажите, какие данные нужны получателю. Часто оказывается, что внешней системе не нужен весь payload: достаточно ID тикета, темы, статуса, приоритета, email клиента и ссылки на карточку. Такой список помогает заранее спроектировать фильтрацию и не отправлять лишние поля.

Этап "безопасный endpoint"

Перед рабочим endpoint используйте безопасный приёмник. Это может быть временный сервис для теста или ваш внутренний маршрут, который пока только пишет событие в журнал. На этом этапе важно увидеть фактические headers, тело запроса, код ответа и поведение SupportCandy logs. Не пытайтесь сразу создать сделку, задачу или инцидент в конечной системе.

Если payload содержит персональные данные, не пересылайте его в публичные инструменты отладки. Внутренний endpoint с коротким сроком хранения логов безопаснее. Для каждого теста фиксируйте: действие в тикете, выбранный триггер, факт доставки, ответ endpoint, наличие подписи и краткий вывод.

Этап "фильтрация и защита от дублей"

Когда payload понятен, добавьте фильтр. Например, новый тикет можно записывать всегда, но уведомление дежурному отправлять только при высоком приоритете. Изменение статуса можно принимать в журнал, но передавать в CRM только если статус действительно изменился на значимый для бизнеса. Такой фильтр лучше держать на стороне обработчика, потому что он проще обновляется и не требует менять настройки каждого вебхука.

Защита от дублей должна появиться до продакшена, а не после первого инцидента. Минимальная логика: если внешний объект с ID тикета уже существует, обновить его, а не создать новый. Для событий SLA добавьте правило, которое не поднимает второй одинаковый инцидент, пока первый не закрыт или не изменился статус тикета.

Этап "рабочая доставка и откат"

После тестов перенесите Delivery URL на рабочий endpoint и выполните один контрольный сценарий. Не меняйте одновременно триггеры, секрет, endpoint и фильтры. Если что-то сломается, вы не поймёте, какое изменение стало причиной. Лучше менять один элемент, проверять результат и только потом двигаться дальше.

Для отката храните три вещи: прежний Delivery URL, прежний набор триггеров и инструкцию, где отключить вебхук. Если внешняя система начала получать лишние события, администратор должен уметь быстро остановить отправку, не дожидаясь разработчика. После остановки разберите logs и журнал endpoint, затем возвращайте интеграцию по одному событию.

Критерий готовности: интеграция готова к рабочему использованию, когда команда может повторить тест, увидеть запрос в логах, объяснить каждый выбранный триггер, проверить подпись и безопасно отключить вебхук при ошибке.

Проверка результата и работа с логами

Документация SupportCandy выделяет webhook logs как место просмотра запросов и ответов. Это ключевой инструмент диагностики. Без логов администратор видит только внешнее последствие: "в CRM ничего не появилось" или "канал молчит". Логи помогают понять, был ли запрос вообще отправлен, какой ответ вернул endpoint и на каком участке цепочка оборвалась.

Что смотреть в логах

После каждого тестового события проверьте три вещи. Во-первых, есть ли запись доставки. Если записи нет, триггер не сработал или вебхук не активен. Во-вторых, какой статус вернул Delivery URL. Успешный HTTP-ответ не всегда означает, что бизнес-действие выполнено, но ошибка уровня 4xx или 5xx точно указывает на проблему принимающей стороны. В-третьих, совпадает ли время события с вашим действием в тикете. Это помогает отличить старую попытку от текущей.

Если лог показывает успешную доставку, но внешняя система молчит, ищите ошибку после endpoint: фильтр по приоритету, неправильный маппинг статуса, дубль, очередь, внутренняя авторизация, ограничение внешнего API. Если лог показывает отказ, начните с URL, SSL, метода запроса, secret key и формата подписи.

Контрольный чек-лист после настройки

• Создан тестовый тикет и получен первый запрос.
• Проверен payload для каждого выбранного триггера.
• Включён и проверен secret key, подпись отклоняет неправильный запрос.
• Внешний endpoint возвращает понятный HTTP-статус и пишет собственный лог.
• Дубли событий не создают дубли записей во внешней системе.
• Персональные и agent-only данные не отправляются в лишние каналы.
• Есть инструкция для команды: где отключить вебхук и где смотреть ошибку.

Мини-итог: настройка считается законченной только после проверки доставки, подписи, payload, фильтрации, логов и отката. Один успешный запрос без анализа тела - ещё не готовая интеграция.

Ограничения, производительность и безопасность

Вебхуки удобны, но они не отменяют инженерные ограничения. У SupportCandy Webhooks есть понятный набор триггеров, секрет для подписи и логи, но надёжность всей интеграции зависит от принимающего endpoint, сети, внешнего API и того, как вы обрабатываете повторные события. Не обещайте команде "абсолютную доставку" без очереди и повторов на вашей стороне.

Скорость ответа endpoint

Если получатель долго думает, зависает или периодически возвращает ошибку, вебхук становится слабым местом. Практичная архитектура - быстро принять запрос, проверить подпись, положить событие в очередь или журнал и ответить. После этого отдельный процесс может отправить данные в CRM, таблицу или канал. Такой подход снижает зависимость WordPress от внешних сервисов.

Обновления и совместимость

В changelog расширения встречались исправления, связанные с обновлением add-ons, совместимостью с Merge ticket feature, URL encoding для Power Automate и действиями в панели настроек. Это хороший пример того, почему после обновлений нужно прогонять короткий регрессионный тест вебхуков. Особенно если Delivery URL содержит спецсимволы, проценты, query string или используется в сервисах автоматизации.

Не вставляйте в статью или публичную документацию точные секреты, токены, application passwords и реальные endpoint с данными клиента. Если нужно показать пример, используйте безопасные фиктивные значения и отдельно храните рабочие переменные.

REST API и вебхуки - не одно и то же

SupportCandy также имеет документацию по REST API. Это другой тип интеграции. Вебхук сообщает внешней системе, что событие произошло. REST API позволяет внешней системе запросить данные, создать тикет или получить список объектов при наличии авторизации. Часто они работают вместе: вебхук сообщает ID тикета, а обработчик затем через API забирает дополнительные данные, если они нужны и разрешены.

Для REST API важна отдельная авторизация. Документация SupportCandy указывает, что API доступны зарегистрированным пользователям и требуют аутентификации. WordPress в свою очередь поддерживает application passwords для Basic Authorization по HTTPS, но для продакшена часто рассматривают более защищённые схемы. Не подменяйте secret key вебхука REST-авторизацией: это разные механизмы для разных сторон обмена.

Когда лучше использовать Workflows, Slack или REST API вместо вебхука

SupportCandy Webhooks закрывает задачу исходящих уведомлений во внешнюю систему, но в экосистеме SupportCandy есть соседние инструменты. Важно выбрать не самый технический, а самый уместный способ.

Workflow/Automations

Workflow/Automations в SupportCandy работает внутри ticketing-системы: триггеры, условия и действия позволяют автоматически менять статус, назначать агента, добавлять приватную заметку или обновлять поля. Если вся логика должна остаться внутри SupportCandy, workflow часто лучше вебхука. Например, "если приоритет High, назначить старшую команду и добавить private note" не обязательно отправлять во внешний endpoint.

Вебхук нужен, когда действие должно выйти за пределы WordPress или когда внешняя система становится источником следующего шага. Часто лучший вариант - связка: workflow нормализует состояние тикета внутри SupportCandy, а webhooks отправляют наружу только уже важные события.

Slack Integration

Slack-интеграция SupportCandy ориентирована на уведомления в канал и возможность ответа из треда, если всё настроено. Если задача команды - быстро увидеть новый тикет и продолжить обсуждение в Slack, специализированная интеграция удобнее, чем самодельный вебхук. Но если нужно отправить данные в несколько систем, фильтровать payload, проверять подпись и строить собственный маршрут, Webhooks остаётся более гибким вариантом.

REST API

REST API выбирайте, когда внешняя система должна сама получать или создавать данные по запросу. Например, ночной отчёт может забирать список тикетов через API, а не ждать вебхук. Но для события "тикет только что вышел за SLA" API менее удобен: придётся опрашивать сайт, тогда как вебхук сразу сообщает о событии. В больших интеграциях эти подходы часто дополняют друг друга.

Безопасные улучшения без правки ядра плагина

Для SupportCandy Webhooks не стоит править файлы плагина, чтобы "добавить ещё одно поле" или изменить отправку. Такие правки потеряются при обновлении и могут сломать доставку. Безопаснее улучшать внешнюю сторону: endpoint, очередь, журнал, фильтрацию и правила обработки. Это даёт контроль, не затрагивая ядро WordPress и SupportCandy.

Журналирование на принимающей стороне

Минимальный безопасный лайфхак - записывать каждое принятое событие в отдельный лог с ID тикета, типом триггера, временем, результатом проверки подписи и итоговым действием. Не сохраняйте лишний payload навсегда, если там есть персональные данные. Для отладки достаточно короткого журнала и временного режима подробной записи.

Идемпотентность вместо борьбы с дублями вручную

Идемпотентность означает, что повторное событие не ломает результат и не создаёт лишние записи. Для вебхуков это практическое правило: внешний обработчик должен уметь понять, что тикет уже есть в CRM или инцидент уже создан. Используйте ID тикета, тип события и актуальное состояние вместо простого "каждый запрос создаёт новую строку".

Мягкий откат

Перед изменением рабочего Delivery URL или набора триггеров сохраните старое значение в защищённых заметках команды. Если после изменения внешняя система начала получать дубли или перестала принимать запросы, откат должен занимать минуты. Не удаляйте вебхук сразу: лучше временно отключить или вернуть прежний endpoint, затем разобрать причину по логам.

Почему вебхук не срабатывает или не доходит

Диагностику лучше вести по цепочке: событие в тикете, настройка вебхука, исходящий запрос, ответ endpoint, обработка внешней системой. Если перескакивать сразу к CRM, можно пропустить очевидную ошибку: не тот триггер, неактивный вебхук, неверный URL или отказ подписи.

В логах нет записи доставки

Симптом: вы создали или изменили тикет, но в webhook logs не видно новой попытки. Возможная причина - выбранный триггер не соответствует действию, вебхук не сохранён, add-on не активен, тест происходит не в том сайте или событие зависит от функции, которая не настроена.

Проверьте, что действие точно соответствует триггеру. Для Change Assignee нужно реально изменить назначение, а не только открыть тикет. Для Out of SLA должны быть настроены SLA-условия. Для agent-only fields нужно изменить именно такое поле и иметь соответствующие права.

Запрос приходит, но внешний сервис возвращает ошибку

Симптом: в логах есть попытка, но ответ endpoint указывает на ошибку. Причина чаще всего на принимающей стороне: неправильный маршрут, авторизация, размер payload, запрет метода, сбой SSL, ограничение firewall или ожидание другого формата данных.

Сначала направьте тот же вебхук на тестовый endpoint и сравните фактический payload с тем, что ожидает внешний сервис. Если сервис требует точный JSON-формат, возможно, нужен промежуточный обработчик, который преобразует данные SupportCandy в нужную схему.

Подпись не совпадает

Симптом: endpoint получает запрос, но ваша проверка X-WPSC-Webhook-Signature отклоняет его. Проверьте secret key, алгоритм HMAC-SHA256, base64-формат, исходный raw payload и то, не меняет ли сервер тело запроса до проверки. Нельзя сравнивать подпись от уже преобразованного JSON, если подпись считалась от исходного тела.

Если используется прокси, балансировщик или middleware, убедитесь, что они не меняют encoding и не удаляют headers. Для временной диагностики можно записать длину raw payload, наличие header и результат вычисления, но не публикуйте секрет и полный payload в общедоступные логи.

События создают дубли

Симптом: один тикет появляется во внешней системе несколько раз. Причина - несколько триггеров ведут к одному действию, обработчик всегда создаёт новую запись или автоматический workflow меняет поле повторно.

Исправление: используйте ID тикета как ключ, храните последнее обработанное состояние и делайте update вместо create. Если нужно создать инцидент только один раз, добавьте флаг на стороне внешней системы или в собственной таблице обработчика.

В канал уходят лишние или чувствительные данные

Симптом: в Slack, таблицу или CRM попали private note, agent-only field или персональная информация, которая не нужна получателю. Причина - пересылка payload без фильтрации.

Остановите вебхук или перенаправьте его на безопасный endpoint, затем добавьте слой фильтрации. Откатите публичное сообщение, если это возможно, и пересмотрите набор триггеров. Для приватных заметок и agent-only fields лучше использовать отдельный защищённый получатель, а не общий канал.

После обновления перестал работать URL с процентами или параметрами

Симптом: Delivery URL раньше работал, а после обновления или изменения внешнего сервиса перестал принимать запросы. В changelog Webhooks были исправления, связанные с URL encoding для Power Automate, поэтому URL со спецсимволами стоит тестировать отдельно.

Проверьте URL в чистом виде, уберите лишние пробелы, сравните тестовый и рабочий endpoint, затем выполните контрольное событие. Если URL содержит сложные параметры, лучше хранить критичные токены на стороне получателя, а не в длинной query string.

Когда SupportCandy Webhooks будет удачным выбором

SupportCandy Webhooks стоит использовать, если у вас уже работает SupportCandy и нужно выводить важные события тикетов во внешнюю систему без ручного экспорта и без правки ядра плагина. Особенно хорошо расширение раскрывается в сценариях, где есть понятный получатель: CRM, incident router, аналитика, внутренний журнал, сервис автоматизации или собственный endpoint с проверкой подписи.

Перед рабочим запуском пройдите короткий путь: один тестовый вебхук, один триггер, проверка payload, включение secret key, просмотр logs, фильтрация данных и защита от дублей. После этого можно подключать дополнительные события. Такой подход медленнее, чем "включить всё", но он экономит время на диагностике и снижает риск утечки лишней информации.

Если вы готовы проверить интеграцию на тестовом тикете и уже понимаете, какие события должны уйти наружу, можно загрузить SupportCandy Webhooks и перейти к настройке на своём сайте. Начинайте с безопасного endpoint, не публикуйте секреты, держите рядом логи и обязательно документируйте, зачем создан каждый вебхук.