Як пояснити невдалу перевірку підпису Webhook партнеру англійською мовою

Пояснення помилки перевірки підпису webhook зовнішньому партнеру є складним балансом: проблема, ймовірно, на його боці, але таке прямое твердження може звучати обвинувачуючою, пошкодити відносини і зробити їх оборонними замість співпраці. Правильна англійська тут достатньо конкретна, щоб допомогти їм впоратися з цим, а також достатньо спільна, щоб вона звучала як “розв’яжемо це разом”, а не “ви поламали це”

Ключовий словник

** Перевірка підпису ** — процес підтвердження того, що вміст webhook справді походить від очікуваного відправника і не було змінено, зазвичай, за допомогою перевірки криптографічного підпису на відповідність спільному секрету.

• « Перевірка підпису зазнала невдачі на нашому кінці для близько 12% ваших вхідних webhooks з часу вчорашнього розгортання. » *

** Схилення годинника ** — різниця між годинниками двох систем, достатньо велика, щоб перевірка часу, наприклад, час підпису, зазнала невдачі, навіть якщо запит є законним.

• “Однією з найпоширеніших причин такого роду помилок є відхилення годинника — якщо годинник вашого сервера відрізняється від нашого більше ніж на п’ ять хвилин, наша перевірка часових штампів відхиляє підпис, який за інших умов буде чинним.” *

** Пересеріалізація вантажу** — ситуація, коли вантаж JSON розбирається і перекодується перед перевіркою підпису, що призводить до незначних змін у представленні байтів (наприклад, порядок ключів або пробіли) і анульовує підпис.

• “Якщо корисне навантаження буде пересеріалізовано де завгодно у вашому конвеєрі до перевірки підпису, навіть нешкідлива зміна, наприклад, порядок ключів, призведе до невдачі перевірки.” *

** Спільний секрет ** — закритий ключ, який використовується обома сторонами для створення і перевірки підпису; якщо будь- яка зі сторін використовує застарілу або не збігається версію, перевірка зазнає невдачі.

• “Чи можете ви підтвердити, який спільний секрет налаштовано на вашому кінці? Ми поміняли наш на 1-й, і це виглядає відповідно до старого секрету, який все ще використовується. ”*

** Необроблений запит ** — точні, незмінені байти вхідного запиту, які слід використовувати для перевірки підпису, а не розшифровану і відновлену версію. “Перевірка підпису має бути виконана на сирому тілі запиту перед будь- яким аналізом JSON — якщо ваша платформа автоматично аналізує тіло на початковому етапі, це є поширеним джерелом цієї проблеми.”

Опис проблеми

• «Ми бачимо невдачі перевірки підпису на приблизно 12% webhooks з вашої інтеграції з 2 липня, і хотіли позначити це, перш ніж це вплине на більший трафік»
• «Глядачи на декілька невдалих прикладів, часові штампи в вантажах постійно на 6-7 хвилин швидше за наш серверний час, що вказує на відхилення годинника як на ймовірну причину»
• «Ми порівняли необроблені байти невдалої корисної нагрузки з тим, що наша система отримала, і порядок ключів відрізняється від успішного — це часто відбувається, коли корисна нагрузка розбирається і пересеріалізується десь перед підписанням»

Використовується в кооперації

• «Це поширена проблема інтеграції і зазвичай має швидке вирішення — ми раді пройти через нашу логіку перевірки разом, якщо це допоможе звузити її»
• « Чи можете ви перевірити, чи синхронізовано годинник вашого сервера за допомогою NTP? Це підтвердило б або виключило теорію годинникового схилу швидко»
• «Тим часом, ми не відключили вашу інтеграцію — ми хотіли підняти це з вами першим, а не блокувати трафік, оскільки ми знаємо, що 88% ваших webhooks все ще успішно перевіряються»

Професійні поради

• ** Використовуйте дані, а не висновки. ** « Ми бачимо невдачі на 12% webhooks з 2 липня » є нейтральним і перевіряним; « ваша інтеграція пошкоджена » запрошує до оборони, навіть якщо ви не запропонували причину.
• ** Надавайте найімовірнішу причину як гіпотезу, а не як звинувачення. ** « Це схоже на відхилення годинника » залишає місце для підтвердження або виправлення, а не для стверджування про помилку до того, як ви побачите їхню сторону системи.
• Згадайте, що все ще працює, а не тільки те, що не працює. Відзначаючи рівень успіху, ви показуєте, що ви точні і справедливі, і запевняєте партнера, що ви не перебільшуєте тяжкості.
• ** Пропонуйте співпрацю з метою виправлення, особливо у випадку будь- чого, що стосується спільної криптографічної логіки. ** Вади перевірки підписів часто є незначними з обох сторін, і пропозиція спільного зневадження, як правило, розв’ язує проблеми швидше, ніж односторонній звіт про ваду.

Практичні вправи

1. Напишіть опис гіпотетичної помилки webhook у двох реченнях, з описом даних, включаючи приблизний рівень помилок і дату початку.
2. Переписати речення « Час вашого сервера неправильний », щоб його було прочитано як гіпотезу, а не як звинувачення.
3. Напишіть одне речення, у якому запропонуєте співпрацювати у зневадженні проблеми перевірки спільного підпису.

Зв’язані ресурси

• Як пояснити затримку поширення DNS англійською мовою

Розрізняють плавальні і неплавальні плавальні

Пояснити невдалу перевірку підпису webhook не завжди легко. Це може бути схоже на вказування пальцем, коли корінь проблеми може бути складним, включаючи незначні відмінності у форматах даних, сертифікатах довіри або навіть просто миттєву помилку. Ключовим є чітке і активне спілкування, зосереджене на розв’язанні, а не на приписуванні вини. Використання точної мови демонструє професіоналізм і повагу до часу і досвіду вашого партнера. Ось як ефективно сформулювати проблему, особливо коли мова йде про когось, для кого англійська не є рідною мовою:

По- перше, уникайте обвинувачувальних фраз на зразок « Спроба перевірки вашого підпису зазнала невдачі ». Замість цього скористайтеся нейтральними твердженнями на зразок « Ми зіткнулися з проблемою під час перевірки вхідного підпису webhook » або « Процес розпізнавання цього запиту зазнав невдачі ». Таким чином, ви негайно перенесете увагу з питання про те, хто винен у цьому, на питання про те, що дійсно виникла проблема. Надалі надайте докладний опис того, що ви спостерігали — коди певних помилок, часових штампів і будь- який відповідний контекст навколо події. Наприклад, «О 2:17 PM GMT, ми отримали відповідь 403 Forbidden, що вказує на недійсний підпис. Вантаж webhook містив…” Цей рівень деталізації показує, що ви ретельно дослідили.

Описуючи технічну природу проблеми, уникайте жаргону, якщо ви не впевнені, що ваш партнер розуміє його повністю. Якщо ви повинні використовувати технічні терміни, негайно поясніть їх простою англійською. Наприклад, замість того, щоб сказати « JWT було неправильно сформовано », спробуйте сказати « Веб- токен JSON містив помилку, яка не дозволила нам перевірити його автентичність ». Ще важливіше, розгляньте проблему як спільне завдання, яке вимагає спільного рішення. Фрази на кшталт «Давайте розслідуємо це разом» або «Ми повинні визначити причину цієї невдачі перевірки» передають готовність працювати з вашим партнером, щоб знайти виправлення.

І нарешті, завжди закінчуйте на активній ноті. Запропонування наступних кроків показує, що ви приймаєте відповідальність і рухаєтеся до вирішення. Наприклад: «Я задокументував ці деталі і поділиться ними з нашою командою безпеки для подальшого аналізу. Чи було б корисно, якби ми запланували короткий дзвінок, щоб обговорити потенційні причини та рішення? »Використання фраз на кшталт «Давайте визначимо пріоритети» або «Ми можемо дослідити варіанти, такі як…», демонструє невідкладність без покладання вину на когось. Пам’ятайте, що мета полягає в тому, щоб збудувати довіру і підтримувати позитивні робочі відносини - чітке, професійне спілкування є найважливішим.