Трансформації

Трансформація перетворює payload події на тіло, якого очікує конкретний отримувач. Збережена подія не змінюється; змінюється лише тіло доставки.

Шаблон

Трансформація — це JSON-документ, рядкові значення якого можуть містити вирази JSONPath у плейсхолдерах ${…}. Плейсхолдери обчислюються відносно payload події; усе інше копіюється як є.

Шаблон

{
  "id": "${$.orderId}",
  "customer": {
    "email": "${$.customer.email}",
    "plan": "${$.subscription.plan_name}"
  },
  "amount_cents": "${$.amount}",
  "note": "Order ${$.orderId} from Railhook"
}

Як записано	Результат
Рядок, що є рівно одним виразом, "${$.amount}"	Значення зі своїм типом: число лишається числом, об’єкт — об’єктом.
Вираз усередині іншого тексту, "Order ${$.orderId} from Railhook"	Рядок із підставленим значенням.
Шлях, що нічого не знаходить	null для виразу на все значення, порожній рядок усередині тексту. Не помилка.

Друкарська помилка в шляху мовчить

Шлях, що нічого не знаходить, не валить шаблон, тож необов’язкове поле лишається необов’язковим. За тим самим правилом шлях із помилкою мовчки дає null. Перегляньте шаблон на реальному payload, перш ніж його підключати.

Шаблон — це не скрипт. Він може прочитати payload і переставити поля; він не може циклитися, звертатися назовні чи обчислювати.

До чого кріпиться трансформація

До чого	Дія
Підписка, transformationId	Збережена трансформація для кожної доставки, яку створює підписка.
Підписка, payloadTemplate	Вбудований шаблон, використовується, коли transformationId не задано.
Правило, дія TRANSFORM	Перекриває трансформацію підписки для подій, що збіглися з правилом. Якщо трансформують кілька правил, діє останнє. Див. Правила.
Призначення, transformationId	Збережена трансформація для пересланих вхідних вебхуків.
Призначення, payloadTransform	Один вираз JSONPath, наприклад $.data, використовується, коли transformationId не задано.
Воркфлоу, вузол transform	Змінює дані всередині воркфлоу. Див. Воркфлоу.

Коли вона виконується

Трансформація застосовується всередині кожної спроби, до обчислення підпису. Підпис покриває вже трансформовані байти, тож отримувач, перевіряючи підпис, перевіряє саме те, що отримав.

Збережену трансформацію шукають у момент спроби. Тому виправлення зламаного шаблону допомагає спробам, які ще попереду.

Зламаний шаблон ніколи не випускає сирий payload

Якщо налаштовану трансформацію не вдається застосувати або transformationId вказує на відсутню чи вимкнену трансформацію, спроба вважається невдалою й повторюється. Первісний payload замість неї ніколи не надсилається, бо трансформації часто прибирають персональні дані, перш ніж вони залишать платформу. Кожна невдача збільшує лічильник transform_failed_total.

Створення та перевірка трансформації

1. Створіть її. name і template обов’язкові; шаблон може мати до 65536 символів.

   curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/transformations" \
     -H "X-API-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name":"Orders to CRM","template":"{\"id\":\"${$.orderId}\",\"amount_cents\":\"${$.amount}\"}"}'

2. Перегляньте результат на вставленому payload через POST /api/v1/projects/{projectId}/transform-preview. Надішліть inputPayload і або transformationId, або вбудований template. Нічого не доставляється.

3. Виконайте сухий прогін доставки через POST /api/v1/projects/{projectId}/transform-preview/delivery-dry-run. Надішліть payload, трансформацію або payloadTemplate і endpointId. Відповідь показує трансформоване тіло, заголовки й підпис, які було б надіслано, а також назву й версію трансформації. Нічого не надсилається.

4. Підключіть її, задавши transformationId у підписці.

У панелі «Студія трансформацій» показує payload і результат поруч та оновлює результат під час набору.

Зміна шаблону трансформації збільшує її версію.

Що далі

ПравилаЗастосовуйте трансформацію лише до подій, що відповідають умові.

ПризначенняТрансформуйте вхідні вебхуки перед пересиланням.

Маскування PIIПриховуйте персональні дані там, де payload читають люди.