Webhooks
Ротація секретного ключа підпису
Безпечно виконуйте ротацію секретного ключа підпису webhook із 24-годинним пільговим вікном подвійного підпису
POST
Огляд
Ayrshare підписує кожну доставку webhook за допомогою HMAC-SHA256 корисного навантаження, використовуючи Ваш секретний ключ підпису, тож Ваш приймач може підтвердити, що доставку справді надіслано з Ayrshare. Див. Безпека Webhook, щоб дізнатися, як працює верифікація. Ротація Вашого секретного ключа підпису дозволяє замінити його за регулярним графіком або негайно, якщо Ви підозрюєте, що його було скомпрометовано. Щоб зробити ротацію безпечною, Ayrshare відкриває 24-годинне пільгове вікно після кожної ротації, протягом якого доставки підписуються обома — попереднім і новим — секретами. Це дозволяє оновити Ваш приймач у власному темпі без втрати чи відхилення жодної доставки — той самий шаблон використовують Stripe і GitHub.Секретний ключ підпису діє на весь профіль: існує один секрет на User Profile (UID),
і він підписує кожну дію webhook, зареєстровану цим профілем. Немає окремого
секретного ключа для окремої дії — встановлення або ротація секрету змінює його для всіх
дій цього профілю одночасно.
Ротація з панелі керування
Ви можете встановити або виконати ротацію секретного ключа підпису на сторінці Webhooks у Developer Dashboard. Панель Signing Secret з’являється над списком Ваших webhook після того, як у профілі буде принаймні один зареєстрований webhook.1
Відкрийте панель Signing Secret
Перейдіть на сторінку Webhooks. Якщо секрет ще не налаштовано, панель показує No signing secret configured з кнопкою Set Signing Secret. Якщо один уже налаштований, вона показує Signing secret configured з кнопкою Rotate.
2
Встановіть або виконайте ротацію
Натисніть Set Signing Secret (перший раз) або Rotate (наявний секрет). Відкриється модальне вікно з попередньо заповненим і показаним надійним, випадково згенерованим секретом. Ви можете Copy його, Regenerate новий або перемкнутися на paste my own, щоб надати власне значення.
3
Підтвердьте
Скопіюйте секрет у безпечне місце — його показано лише один раз, і його ніколи неможливо буде отримати з UI знову — потім підтвердьте, щоб надіслати. З’явиться повідомлення про успіх, і панель оновиться.
4
Оновіть Ваш приймач
Під час ротації (не першого встановлення) панель показує індикатор активного пільгового вікна, а кнопка Rotate вимкнена до закриття вікна. У Вас є 24 години, щоб розгорнути новий секрет на Вашому приймачі.
Ротація через API
Виконайте ротацію (або встановіть) секретного ключа підпису одним викликом. Це створює новий секрет, перепризначає посилання на секрет профілю на нього і — коли існував наявний секрет — записує заміщений секрет як попередній секрет із терміном дії 24 години.Header Parameters
Body Parameters
string
обов'язково
Значення нового секретного ключа підпису. Приймається будь-який непорожній рядок. Рекомендуємо довге, високоентропійне випадкове значення (наприклад, 32 випадкових байти в кодуванні base64url).
secret ніколи не повертається у відповіді та ніколи не логується. Відповідь містить клієнтський refId (хеш UID), ніколи не сам UID. Заголовок Profile-Key необов’язковий і обмежує ротацію одним User Profile для акаунтів із кількома профілями.
Відсутній або порожній secret повертає зіставлену помилку (code: 101, “Missing/incorrect parameter”) зі статусом HTTP 400, і жодних змін до Вашого поточного секрету не вноситься. Перше встановлення через API (за відсутності наявного секрету) створює секрет без запису попереднього секрету та без пільгового вікна.
Безпечна процедура ротації
Завдяки 24-годинному пільговому вікну немає обов’язкового порядку дій — Ваш приймач продовжує працювати протягом усього процесу. Рекомендована послідовність:1
Виконайте ротацію секрету
Виконайте ротацію з панелі керування або через API. Ayrshare одразу починає підписувати доставки обома — попереднім і новим — секретами.
2
Оновіть Ваш приймач
Протягом 24 годин розгорніть новий секрет на Вашому приймачі webhook, щоб він верифікував за новим значенням.
3
Дайте вікну закритися
Через 24 години Ayrshare автоматично очищує попередній секрет і підписує лише новим секретом. Ніяких додаткових дій з Вашого боку не потрібно.
Верифікація підписів під час пільгового вікна
Поза пільговим вікном підписані доставки містять стандартні заголовки (див. Безпека Webhook):X-Authorization-Content-SHA256-V2 містить обидва підписи, поточний першим, розділені комою:
X-Authorization-Content-SHA256 не змінюється: він завжди містить єдиний
HMAC поточного секрету для зворотної сумісності. Подвійні підписи з’являються лише в
новому заголовку X-Authorization-Content-SHA256-V2.X-Authorization-Content-SHA256-V2 має префікс тега схеми. v1= позначає підпис HMAC-SHA256, обчислений точно так, як X-Authorization-Content-SHA256. Заголовок -V2 завжди присутній, коли доставку підписано — він містить принаймні v1=<current-sig> — тож Ви можете покладатися на нього як на стабільний контракт приймача.
Щоб верифікувати доставку під час (або поза) ротацією:
1
Обчисліть HMAC
Обчисліть HMAC-SHA256 сирого тіла запиту, використовуючи локально налаштований секретний ключ підпису.
2
Порівняйте з кожним переліченим підписом
Прочитайте
X-Authorization-Content-SHA256-V2, розділіть його за комами, зніміть префікс v1= з кожного значення та прийміть доставку як автентичну, якщо Ваш обчислений HMAC збігається з будь-яким переліченим підписом v1=.v1=<previous-sig>, тоді як приймач, оновлений до нового секрету, збігається з v1=<current-sig> — обидва проходять успішно протягом вікна.
Приклад верифікації на приймачі
Node.js
