Що таке 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
Якщо HTTP-відповідь Вашого сервера не в діапазоні успіху200-299, або Ваш сервер не відповість протягом 15 секунд, система автоматично повторить виклик Webhook ще двічі. Перша повторна спроба буде через 5 секунд, а друга — через 30 секунд. Повторні спроби матимуть той самий hookId і той самий payload.
Семантика доставки та ідемпотентність
Ayrshare доставляє webhook щонайменше один раз. Періодичні дублікати — це нормальна робота, а не дефект — кожен споживач потребує ідемпотентності як постійної властивості. Дублікати приходять у двох різних формах, і кожна потребує іншого ключа:hookId ідентифікує одну доставку події. Він ідентичний при кожній повторній спробі цієї доставки, тому претензія на нього робить повторні спроби безпечними — але нове сповіщення про ту саму базову подію приходить із новим hookId, тож сам по собі hookId не розпізнає цей випадок.
Рекомендований шаблон приймача:
- Спочатку відповідайте. Поверніть
2xxнегайно, а потім обробляйте асинхронно. Тайм-аут не є відмовою — якщо Ви завершите роботу, але відповісте із запізненням, подію буде надіслано знову. - Атомарно заявляйте
hookIdу момент надходження запиту — унікальне обмеження,INSERT ... ON CONFLICT DO NOTHINGабоSET NX— не перевірка «прочитати-потім-записати». Дві спроби можуть надійти одночасно, і захист типу «перевірити-потім-діяти» пропустить обидві. - Заявляйте також власний ключ, побудований з payload, щоб друге сповіщення з новим
hookIdусе одно було розпізнане. Дляmessagesдобре працюєidу поєднанні зsubAction. - І тільки потім виконуйте роботу, утримуючи обидві претензії достатньо довго, щоб покрити вікно повторних спроб і будь-яке пізніше повторне сповіщення.
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.X-Authorization-Content-SHA256 з HMAC-SHA256 тіла POST. Секретний ключ підпису діє на весь профіль — один секрет на User Profile, який використовується для всіх дій webhook цього профілю, тому встановлення його для однієї дії змінює його для всіх дій цього профілю. Акаунти з кількома профілями керують окремим секретом для кожного профілю (націльтеся на профіль за допомогою заголовка Profile-Key).