Skip to main content

​
Що таке Webhook?

Webhook дозволяє отримувати сповіщення, коли відбуваються певні дії системи, через виклик URL, який Ви надаєте. Webhook також відомі як “URL Callbacks” або “HTTP push calls”. Ваш URL повинен використовувати SSL і починатися з HTTPS.

Дії Webhook

Перегляньте доступні дії для webhook.

​
Розуміння Webhook Ayrshare

Webhook класифіковані за конкретною дією і реєструються на рівні Primary Profile або User Profile. Будь-які оновлення для Primary або User Profiles спочатку надсилаються до зареєстрованого Webhook для User Profile. Якщо User Profile не має зареєстрованого Webhook, оновлення буде надіслано до зареєстрованого Webhook Primary Profile. Наприклад:
  • Якщо User Profile має зареєстрований Social Action Webhook і від’єднує TikTok, буде викликано зареєстрований URL Social Action Webhook для User Profile. Webhook Primary Profile не буде викликано.
  • Якщо User Profile від’єднує TikTok і не має зареєстрованого Social Action Webhook, але Primary Profile має зареєстрований Webhook, буде викликано зареєстрований URL Social Action Webhook для Primary Profile.

​
Реєстрація Webhook

Зареєструйте Webhook, надавши URL кінцевої точки та тип дії до кінцевої точки POST /hook/webhook. Коли дія відбувається, до наданого URL надсилається повідомлення HTTP POST. Наприклад, зареєструйте URL для отримання сповіщень про статус запланованого допису. URL кінцевої точки Webhook не повинен використовувати перенаправлення і має бути кінцевим URL призначення. Якщо Ви зареєструєте лише webhook Primary Profile, User Profiles автоматично успадкують webhook Primary Profile. Щоб мати унікальний webhook для кожного User Profile, Ви повинні зареєструвати webhook для кожного User Profile.
Після отримання Вашим Webhook HTTP POST, Ваш сервер повинен відповісти HTTP-статусом 200, щоб позначити виклик як успішний. Якщо Ваш сервер не відповість протягом 15 секунд, спробу буде записано як невдалу та повторено. Відповідайте одразу після отримання запиту та виконуйте обробку асинхронно — тайм-аут не є відмовою, тож якщо Ваш обробник завершить роботу, але відповість із запізненням, повторна спроба призведе до подвійної обробки.
Ви також можете зареєструвати webhook у Developer Dashboard.

​
Повторні спроби Webhook

Чи буде повторено невдалу доставку, залежить від того, як саме вона не вдалася. Кожна повторна спроба несе той самий hookId. Payload створюється заново для кожної спроби, тому timeStamp — і підпис над ним — можуть відрізнятися. Повторюється — тимчасові збої. Відповідь 429, 408 або 425, будь-яка 5xx, тайм-аут чи розірване з’єднання отримує щонайбільше 9 спроб надсилання протягом приблизно години — перше надсилання плюс 8 повторів. Якщо після цього збій триває, доставку намагаються виконати знову за спадним розкладом — приблизно через 5 хвилин, 30 хвилин, 2 години та 12 годин. Тому доставка може надійти навіть через приблизно 16 годин після початкової події. Не повторюється — відмови. Будь-яка інша відповідь 4xx, наприклад 400, 401, 403, 404 або 410, вважається остаточною з першої спроби. Вони означають, що сам запит було відхилено, і повторення не змінить результату.
Якщо ваш endpoint повертає 4xx лише час від часу — 404 під час розгортання або 401 через щойно прострочені дані доступу — така доставка не буде повторена. GET /hook/history (Premium) показує ваші останні доставки, щоб ви побачили, які з них не вдалися. Це лише читання — він нічого не надсилає повторно.

​
Семантика доставки та ідемпотентність

Ayrshare доставляє webhook щонайменше один раз. Періодичні дублікати — це нормальна робота, а не дефект — кожен споживач потребує ідемпотентності як постійної властивості. Дублікати приходять у двох різних формах, і кожна потребує іншого ключа: hookId ідентифікує одну доставку події. Він ідентичний при кожній повторній спробі цієї доставки, тому претензія на нього робить повторні спроби безпечними — але нове сповіщення про ту саму базову подію приходить із новим hookId, тож сам по собі hookId не розпізнає цей випадок. Рекомендований шаблон приймача:
  1. Спочатку відповідайте. Поверніть 2xx негайно, а потім обробляйте асинхронно. Тайм-аут не є відмовою — якщо Ви завершите роботу, але відповісте із запізненням, подію буде надіслано знову.
  2. Атомарно заявляйте hookId у момент надходження запиту — унікальне обмеження, INSERT ... ON CONFLICT DO NOTHING або SET NX — не перевірка «прочитати-потім-записати». Дві спроби можуть надійти одночасно, і захист типу «перевірити-потім-діяти» пропустить обидві.
  3. Заявляйте також власний ключ, побудований з payload, щоб друге сповіщення з новим hookId усе одно було розпізнане. Для messages добре працює id у поєднанні з subAction.
  4. І тільки потім виконуйте роботу, утримуючи обидві претензії достатньо довго, щоб покрити вікно повторних спроб і будь-яке пізніше повторне сповіщення. Оскільки повторна спроба може надійти навіть через приблизно 16 годин, утримуйте свої претензії щонайменше 24 години. Претензія, яка спливе раніше, не розпізнає пізню повторну спробу, і ви обробите ту саму подію двічі.
id у payload не є унікальним сам по собі для кожного типу події — той самий message id повторюється між редагуваннями та реакціями, а payload messageRead не містить id — тому поєднуйте його з subAction, а не використовуйте окремо.

​
Заголовки метаданих доставки

Кожна доставка несе два заголовки, що ідентифікують саме цю передачу, щоб Ви могли відрізнити оригінал від повторної спроби:
X-Ayrshare-Delivery-Attempt дорівнює 0 при першому надсиланні та збільшується на одиницю при кожній повторній спробі, тож будь-яке значення понад 0 означає, що ми вже надсилали цю доставку щонайменше один раз. Розглядайте його як необмежений лічильник, а не як фіксований набір значень — кількість повторних спроб є операційною деталлю, яка може змінюватись. X-Ayrshare-Delivery-Id унікальний для кожної спроби — процитуйте його підтримці, і він ідентифікує точний запис доставки. Вони ідентифікують передачу; hookId ідентифікує подію. Дедуплікуйте за hookId, а не за delivery id — delivery id за задумом різний при кожній спробі, тож нічого ніколи не буде розпізнано як дублікат.

​
Безпека Webhook

Ви можете додати додаткову безпеку, встановивши автентифікацію HMAC як HTTP-запит. Це часто робиться для запобігання атакам відтворення. Ayrshare використовує HMAC-SHA256 для хешування тіла повідомлення та включає його разом із UNIX timestamp у заголовок POST.
На основі секретного ключа, встановленого при реєстрації Вашого webhook, Ви можете валідувати POST, порівнявши заголовок X-Authorization-Content-SHA256 з HMAC-SHA256 тіла POST. Секретний ключ підпису діє на весь профіль — один секрет на User Profile, який використовується для всіх дій webhook цього профілю, тому встановлення його для однієї дії змінює його для всіх дій цього профілю. Акаунти з кількома профілями керують окремим секретом для кожного профілю (націльтеся на профіль за допомогою заголовка Profile-Key).

​
Журнали Webhook

У Ayrshare Dashboard Ви можете переглядати активні webhook, бачити деталі надісланого Webhook, статус відповіді Вашого сервера та повторно надсилати Webhook на зареєстрований URL. Переключіться на конкретний User Profile, щоб переглядати журнали Webhook цього профілю.

​
Коди відповідей HTTP

Перший стовпець показує успішну HTTP-відповідь ✔️ (200, 300) від Webhook або невдалу відповідь ✖️ (400, 500). Переключіться на конкретний user profile, щоб переглядати журнали Webhook цього профілю.

​
Відсоток помилок

“Error Rate” з останніх 1 000 дописів можна переглянути на сторінках Actions та Webhook Logs у панелі керування. Будь-яка відповідь webhook від Вашого сервера з кодом 400-500 вважається помилкою.