Skip to main content
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 автоматично очищує попередній секрет і підписує лише новим секретом. Ніяких додаткових дій з Вашого боку не потрібно.
Якщо Ви виконуєте ротацію знову, поки пільгове вікно ще відкрите, щойно заміщений секрет стає новим попереднім секретом, і починається нове 24-годинне вікно. Одночасно зберігається лише один попередній секрет.

Верифікація підписів під час пільгового вікна

Поза пільговим вікном підписані доставки містять стандартні заголовки (див. Безпека Webhook):
Протягом 24-годинного вікна після ротації новий заголовок 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
Завжди обчислюйте HMAC над сирими байтами тіла запиту, точно як отримано — не над повторно серіалізованим JSON-об’єктом. Повторна серіалізація може змінити пробіли або порядок ключів і зламати верифікацію. Використовуйте порівняння з постійним часом (наприклад, crypto.timingSafeEqual), щоб уникнути timing-атак.
Якщо для доставки відсутній запис поточного секрету, доставка виконується без підпису (без заголовків підпису), а не з помилкою. Якщо відсутній лише запис попереднього секрету, попередній підпис пропускається, а поточний підпис усе одно надсилається в обох заголовках.