Налаштування вебхуків

Published: 16 липня 2026 р. · Last updated: 21 липня 2026 р. · By Marcus Biel

Вебхуки дають змогу Maildroppa повідомляти іншу програму, коли у вашому обліковому записі відбувається щось важливе.

Замість того щоб постійно запитувати Maildroppa, чи було створено, оновлено або відписано підписника, чи призначено йому тег, ваша програма може отримати HTTPS-запит невдовзі після настання події.

Сторінка Webhooks — центральне місце для цієї інтеграції на рівні облікового запису. Ви можете створити кілька кінцевих точок, вибрати події для кожної з них, додати заголовки автентифікації, перевірити з’єднання, переглянути спроби доставки та за потреби повторно відтворити робочу подію.

Як працюють вебхуки облікового запису

Вебхук облікового запису працює так:

1. У Maildroppa відбувається подія, наприклад створюється підписник.
2. Maildroppa знаходить кожну активну кінцеву точку, підписану на цю подію.
3. Maildroppa створює одну доставку для кожної відповідної кінцевої точки.
4. JSON-корисне навантаження підписується секретом підпису вебхуків вашого облікового запису.
5. Maildroppa надсилає HTTPS-запит POST на збережену URL-адресу кінцевої точки.
6. Ваша кінцева точка перевіряє підпис, зберігає або обробляє подію та повертає HTTP-відповідь.
7. Maildroppa записує результат в історію доставок і автоматично повторює спроби після тимчасових помилок.

Якщо на одну подію підписано кілька кінцевих точок, кожна з них отримує власну доставку. Бізнес-подія має однаковий ідентифікатор події для всіх них, тоді як кожна доставка має власний ідентифікатор доставки.

Вебхуки облікового запису відрізняються від кроку «Надіслати вебхук» усередині автоматизації. Вебхуки облікового запису прослуховують вибрані події облікового запису в Maildroppa. Вебхук автоматизації надсилається лише тоді, коли підписник досягає відповідного кроку. Обидва використовують секрет підпису вебхуків облікового запису, тому зміна секрету впливає на всі одержувачі вихідних вебхуків, які перевіряють підписи Maildroppa.

Відкриття сторінки Webhooks

Відкрийте «Settings», розгорніть «Developers» і виберіть «Webhooks».

Сторінка містить три основні області:

• Секрет підпису
• Кінцеві точки
• Історія доставок для вибраної кінцевої точки

Якщо у вас більше однієї кінцевої точки, виберіть рядок кінцевої точки, щоб відобразити її історію доставок. Якщо ви явно не вибрали кінцеву точку, Maildroppa покаже історію першої кінцевої точки у списку.

Перед створенням кінцевої точки

Підготуйте одержувач на своєму сервері перед налаштуванням Maildroppa. Одержувач має:

• Бути доступним за загальнодоступною HTTPS-адресою.
• Приймати запити POST із тілом application/json.
• Зберігати необроблене тіло запиту, доки підпис Maildroppa не буде перевірено.
• Повертати статус 2xx лише після безпечного прийняття події.
• Ідемпотентно обробляти повторні доставки, використовуючи ідентифікатор події.
• Швидко відповідати, не виконуючи повільні операції під час запиту.

Надійний підхід — перевірити запит, зберегти ідентифікатор події та корисне навантаження у надійній черзі або базі даних, повернути 200 або 204, а потім виконати бізнес-операцію.

Не використовуйте комп’ютер для розробки, локальну мережеву адресу або незахищений скрипт як робочий одержувач вебхуків. Maildroppa приймає лише загальнодоступні HTTPS-цілі та повторно перевіряє призначення під час надсилання доставки.

Крок 1: створіть секрет підпису

Кожен запит вебхука Maildroppa підписується. Ваш одержувач використовує секрет підпису, щоб перевірити, що запит створено Maildroppa і що тіло не було змінено під час передавання.

У верхній частині сторінки панель секрету підпису показує один із таких станів:

• Missing — секрету підпису ще немає.
• Ready — секрет підпису налаштовано.
• Loading — Maildroppa отримує поточний стан.

Натисніть «Generate secret», коли станом є Missing.

Maildroppa негайно відобразить новий секрет. Він починається з whsec_. Натисніть «Copy» і збережіть його в менеджері секретів або захищеній конфігурації середовища, яку використовує ваш одержувач.

Повне значення показується лише одразу після створення або зміни секрету. Після перезавантаження сторінки або виходу з неї Maildroppa показує лише наявність секрету та час його останнього оновлення. Збережений секрет повторно не розкривається.

Якщо ви втратили секрет

Якщо в одержувача більше немає поточного секрету, натисніть «Rotate secret» і збережіть нове відображене значення.

Зміна секрету негайно замінює попередній. Maildroppa не зберігає обидва значення протягом перехідного періоду. Оновіть кожного одержувача, який використовує цей секрет облікового запису, перш ніж надсилати подальші тести або покладатися на робочі доставки.

Нові доставки, заплановані повторні спроби, тести та повторні відтворення підписуються поточним секретом у момент HTTP-запиту. Це означає, що доставка, створена до зміни секрету, під час подальшої спроби все одно може бути підписана новим секретом.

Ставтеся до секрету як до пароля

Не розміщуйте секрет підпису в коді браузера, загальнодоступному репозиторії, URL-адресі, сторінці помилки або звичайному журналі програми.

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

Перевірка підпису вебхука

Кожен запит містить такі заголовки Maildroppa:

• X-Maildroppa-Event-Id — ідентифікує бізнес-подію.
• X-Maildroppa-Delivery-Id — ідентифікує конкретну доставку.
• X-Maildroppa-Timestamp — час підпису в секундах Unix.
• X-Maildroppa-Signature — версійований підпис HMAC.

Maildroppa також надсилає:

• Content-Type: application/json
• User-Agent: Maildroppa-Webhooks/1.0

Підпис має такий формат:

v1=<lowercase hexadecimal HMAC>

Maildroppa створює його за допомогою HMAC-SHA256. Підписаний вміст — це мітка часу, за якою йде крапка, а потім точне необроблене тіло JSON-запиту:

<timestamp>.<raw request body>

Використовуйте секрет підпису як ключ HMAC.

Наведений нижче приклад Node.js демонструє основний крок перевірки. rawBody має містити оригінальні байти запиту, а не JSON, який уже було розібрано та повторно серіалізовано.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

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

Розбирайте та обробляйте JSON лише після успішного проходження обох перевірок.

Поширені причини помилок підпису

Підпис зазвичай не проходить перевірку з однієї з таких причин:

• Після зміни секрету одержувач використовує старий секрет.
• Проміжне програмне забезпечення розібрало або змінило JSON до обчислення підпису.
• Одержувач підписує лише тіло та пропускає <timestamp>..
• Мітку часу трактують як форматовану дату замість точного значення заголовка.
• Порівняння виконується без префікса v1=.
• Обчислений HMAC закодовано не в нижньому регістрі шістнадцяткової системи.

У разі помилки перевірки записуйте ідентифікатори події та доставки, але ніколи не записуйте секрет підпису або конфіденційні значення власних заголовків.

Крок 2: додайте кінцеву точку

Натисніть «Add endpoint» у розділі Endpoints.

Редактор містить чотири частини:

• URL-адреса кінцевої точки
• Події
• Власні заголовки
• Активний стан

Нові кінцеві точки починаються як активні, а всі події, показані в редакторі, спочатку вибрані. Перевірте вибір перед збереженням, щоб одержувач отримував лише потрібні сповіщення.

Налаштування URL-адреси кінцевої точки

Введіть повну загальнодоступну URL-адресу, яка має отримувати запити Maildroppa, наприклад:

https://integrations.example.com/webhooks/maildroppa

URL-адреса має відповідати таким вимогам:

• Має використовувати https://.
• Має містити дійсне загальнодоступне ім’я хоста.
• Може містити до 2 048 символів.
• Не може містити змінні шаблону з { або }.
• Не може містити ім’я користувача або пароль перед іменем хоста.
• Не може містити фрагмент URL, що починається з #.
• Має використовувати стандартний HTTPS-порт 443.
• Не може використовувати localhost, необроблену IP-адресу або ім’я хоста, яке розпізнається як заблокована приватна чи зарезервована мережа.

Параметри запиту підтримуються, але не розміщуйте API-ключі чи інші секрети в URL-адресі. URL-адреси видно у списку кінцевих точок і даних доставки. Натомість використовуйте власний заголовок для облікових даних.

Maildroppa не переходить за перенаправленнями. Збережіть кінцеве HTTPS-призначення, а не URL-адресу, яка повертає 301, 302, 307 або 308.

Ім’я хоста призначення повторно розпізнається перед надсиланням. Якщо згодом ім’я хоста розпізнається як приватна або заблокована адреса, запит буде відхилено, навіть якщо під час збереження кінцева точка була дійсною.

Вибір подій

Виберіть принаймні одну подію. Кінцева точка отримує лише типи подій, вибрані в її редакторі.

На сторінці доступні такі події:

Subscriber Created — subscriber.created

Надсилається, коли в обліковому записі Maildroppa створюється підписник.

Використовуйте цю подію, щоб створити відповідний контакт у CRM, платформі даних клієнтів, внутрішній базі даних або іншій системі, що враховує дозволи.

Не сприймайте цю подію як підтвердження того, що кожна реєстрація завершила подвійне підтвердження підписки. Статус підписника в корисному навантаженні описує поточний стан.

Subscriber Updated — subscriber.updated

Надсилається, коли змінюється вбудована інформація про підписника або значення власних полів.

Використовуйте повний об’єкт підписника в корисному навантаженні як поточне представлення Maildroppa. Не припускайте, що змінилася лише певна властивість.

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

Subscriber Unsubscribed — subscriber.unsubscribed

Надсилається, коли підписник переходить у стан відписки внаслідок дії з відписки.

Використовуйте цю подію, щоб придушити контакт у підключених системах. Не підписуйте особу автоматично повторно лише тому, що інша система все ще позначає контакт як активний.

Tag Added — subscriber.tag_added

Надсилається, коли підписнику призначається тег.

Корисне навантаження містить підписника й тег, пов’язані саме з цією зміною.

Tag Removed — subscriber.tag_removed

Надсилається, коли тег видаляється з підписника.

Корисне навантаження містить оновленого підписника та видалений тег. Видалений тег передається окремо, навіть якщо його вже немає в поточному масиві tags підписника.

Form Submitted — form.submitted

Надсилається, коли відвідувач надсилає форму реєстрації Maildroppa.

Сприймайте це як сигнал надсилання форми, а не як підтвердження завершення подвійного підтвердження підписки. Будь-який процес, що потребує підтвердженої підписки, має й надалі враховувати поточний статус підписника та процес підтвердження.

Використовуйте окремі кінцеві точки, якщо обов’язки різняться

Ви можете надсилати різні події в різні системи. Наприклад:

• Надсилати події підписників і тегів до CRM.
• Надсилати події відписки до служби придушення.
• Надсилати події надсилання форм до аналітичного конвеєра.

Окремі кінцеві точки зменшують непотрібний трафік і спрощують діагностику помилок. Кожна кінцева точка має власний вибір подій, URL-адресу, власні заголовки, активний стан, тести та історію доставок.

Додавання власних заголовків

Власні заголовки необов’язкові. Використовуйте їх, коли одержувач потребує API-ключа, токена bearer, ідентифікатора клієнта або іншого фіксованого заголовка.

Натисніть «Add header», потім введіть назву й значення заголовка. Приклади:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Можна додати до 20 власних заголовків.

Назви заголовків:

• Обов’язкові.
• Можуть містити до 128 символів.
• Мають використовувати дійсні символи назв HTTP-заголовків.
• Мають бути унікальними без урахування регістру.

Значення заголовків:

• Обов’язкові.
• Можуть містити до 2 000 символів.
• Не можуть містити переносів рядків.

Такі назви зарезервовані й не можуть бути замінені власним заголовком:

• Content-Type
• Content-Length
• Host
• User-Agent
• Будь-яка назва, що починається з X-Maildroppa-

Це запобігає заміні власним значенням заголовків доставки та підпису Maildroppa.

Як зберігаються секрети заголовків

Maildroppa шифрує значення власних заголовків перед збереженням. Збережені значення не повертаються браузеру у зрозумілому вигляді.

Коли ви згодом редагуєте кінцеву точку, поле значення показує «Stored value kept». Залиште його порожнім, якщо наявний секрет має залишитися без змін. Введіть нове значення, щоб замінити його.

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

Видалення рядка заголовка видаляє цей заголовок із майбутніх доставок після збереження кінцевої точки.

Значення власних заголовків вважаються конфіденційними у збереженій інформації про запити. В історії доставок вони маскуються, а не відображаються.

Встановлення активного або неактивного стану кінцевої точки

Залиште «Active» вибраним, коли кінцева точка готова негайно приймати події.

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

Неактивна кінцева точка:

• Не отримує нові події.
• Не може надсилати тестовий вебхук.
• Залишається видимою та доступною для редагування.
• Зберігає доступну наявну історію доставок.

Активація кінцевої точки не заповнює заднім числом події, що відбулися, коли вона була неактивною.

Натисніть «Save», коли URL-адреса, вибір подій, заголовки та стан правильні.

Розуміння списку кінцевих точок

Кожен рядок кінцевої точки показує:

• URL-адресу призначення.
• Позначку Active або Inactive.
• Типи подій, на які виконано підписку.
• Кількість власних заголовків.
• Час останнього оновлення кінцевої точки.

Доступні дії:

• On/Off — активує або деактивує кінцеву точку.
• Test — надсилає один негайний тестовий запит до активної кінцевої точки.
• Edit — змінює URL-адресу, події, заголовки або активний стан.
• Delete — назавжди видаляє конфігурацію кінцевої точки після підтвердження.

Виберіть основну частину рядка, щоб відкрити історію доставок цієї кінцевої точки під списком.

Як збережені зміни впливають на наявні доставки

Подія облікового запису створює доставку зі знімком URL-адреси кінцевої точки, корисного навантаження та власних заголовків у цей момент.

Редагування URL-адреси або власних заголовків впливає на новостворені доставки. Доставка, яка вже стоїть у черзі, зберігає початкове призначення та збережену конфігурацію заголовків.

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

Секрет підпису працює інакше: він зчитується під час підготовки HTTP-запиту. Тому доставка в очікуванні або повторне відтворення можуть використовувати новий секрет підпису, навіть якщо їхнє корисне навантаження та знімок кінцевої точки було створено раніше.

Тестування кінцевої точки

Натисніть «Test» на активній кінцевій точці після підготовки одержувача та секрету підпису.

Maildroppa негайно надсилає один підписаний запит, використовуючи збережену URL-адресу кінцевої точки та збережені власні заголовки. Незбережені зміни у відкритому редакторі до тесту не входять.

Тестове корисне навантаження використовує тип події webhook.test і встановлює livemode у false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

Згенеровані ідентифікатори та мітка часу відрізняються для кожного реального тесту.

Тест виконує рівно одну спробу HTTP-запиту. Тестові доставки не додаються до робочого розкладу повторних спроб і не можуть бути повторно відтворені.

Після завершення запиту панель результатів показує:

• Успішний або невдалий тест
• Ідентифікатор події
• Статус HTTP, якщо було отримано відповідь
• Тривалість
• Ідентифікатор доставки
• Інформацію про помилку, якщо доступна
• Фрагмент відповіді, якщо одержувач повернув тіло

Тест також з’являється в історії доставок із позначкою Test. Використовуйте фільтр «Test», щоб показати лише тестові запити.

Розуміння робочого корисного навантаження

Події облікового запису в робочому середовищі використовують спільну JSON-оболонку:

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

Властивості верхнього рівня означають:

• id — ідентифікатор події. Відповідає X-Maildroppa-Event-Id.
• type — ключ події, вибраний у редакторі кінцевої точки.
• schema_version — версія схеми корисного навантаження. Використовуйте її, вирішуючи, як розбирати подію.
• created_at — час створення корисного навантаження події, UTC.
• livemode — true для робочих подій і false для тестових.
• data — вміст, специфічний для події.

Маршрутизуйте події за точним значенням type. Ігноруйте додаткові властивості, які не потрібні вашій інтеграції, щоб сумісні доповнення корисного навантаження не порушували роботу одержувача.

Корисне навантаження події підписника

Події підписника містять поточне представлення підписника всередині data.subscriber:

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields і tags — це масиви. Вони можуть бути порожніми. Властивість підписника також може мати значення null, якщо значення немає, тому одержувач має дотримуватися схеми корисного навантаження, а не припускати наявність кожного необов’язкового значення профілю.

Корисне навантаження події тегу

Події тегів містять і підписника, і тег, що спричинив подію:

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

Для subscriber.tag_removed значення data.tag все одно ідентифікує видалений тег, хоча поточний масив tags підписника більше його не містить.

Ідентифікатори подій, доставки та ідемпотентність

Ідентифікатор події та ідентифікатор доставки мають різне призначення.

Ідентифікатор події

Ідентифікатор події ідентифікує бізнес-подію. Він міститься в:

• Властивості верхнього рівня id корисного навантаження.
• Заголовку запиту X-Maildroppa-Event-Id.
• Історії доставок.

Одна подія може надсилатися кільком підписаним кінцевим точкам. Такі доставки мають спільний ідентифікатор події.

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

Ідентифікатор доставки

Ідентифікатор доставки ідентифікує один запис доставки. Він міститься в:

• Заголовку запиту X-Maildroppa-Delivery-Id.
• Історії доставок.

Кожна доставка кінцевій точці має власний ідентифікатор доставки. Ручне повторне відтворення створює новий ідентифікатор доставки, зберігаючи початковий ідентифікатор події.

Використовуйте ідентифікатор доставки для технічного трасування та підтримки. Використовуйте ідентифікатор події для дедуплікації на рівні бізнесу.

Повернення правильного HTTP-відповіді

Maildroppa класифікує відповіді так:

• Будь-яка відповідь 2xx позначає доставку як успішну.
• Відповіді 408 Request Timeout, 429 Too Many Requests і 5xx є тимчасовими помилками та можуть повторюватися.
• Мережеві помилки, які можуть бути тимчасовими, повторюються.
• Перенаправлення та інші відповіді 3xx не обробляються та вважаються остаточними помилками.
• Інші відповіді 4xx вважаються остаточними помилками та не повторюються.

Поверніть 200, 202 або 204 лише після безпечного прийняття події. Якщо обробка потребує часу, спочатку збережіть подію та поверніть успішну відповідь, а повільнішу роботу виконайте асинхронно.

Не повертайте перенаправлення на іншу URL-адресу вебхука. Натомість налаштуйте кінцеву URL-адресу в Maildroppa.

Автоматичний розклад повторних спроб

Робочі доставки можуть виконувати до семи HTTP-спроб.

Після помилки, що допускає повторну спробу, Maildroppa планує наступну спробу з такими затримками:

1. Після спроби 1: 1 хвилина
2. Після спроби 2: 5 хвилин
3. Після спроби 3: 30 хвилин
4. Після спроби 4: 2 години
5. Після спроби 5: 12 годин
6. Після спроби 6: 24 години

Якщо під час спроби 7 усе ще отримано помилку, що допускає повторення, доставка стає мертвою, і подальші автоматичні спроби не плануються.

Розклад відраховується від окремих невдалих спроб. Фактичний час доставки може бути трохи пізнішим, оскільки доставки обробляються асинхронно та також залежать від системних обмежень захисту.

За можливості усуньте тимчасову проблему одержувача до часу, показаного в «Next retry». Якщо автоматичні спроби завершилися, використайте Replay після відновлення роботи одержувача.

Розуміння історії доставок

Історія доставок належить поточній вибраній кінцевій точці. URL-адреса кінцевої точки відображається в заголовку розділу, щоб ви могли підтвердити, яку історію переглядаєте.

Використовуйте такі фільтри:

• All — показує робочі та тестові доставки.
• Production — показує лише доставки робочих подій.
• Test — показує лише ручні тести.

Натисніть «Refresh», щоб отримати найновіший стан. Не потрібно залишати історію відкритою, поки Maildroppa надсилає або повторює доставку.

На сторінці показуються 50 останніх відповідних доставок для вибраного фільтра.

Стовпці доставки

Кожен рядок містить:

• Created — час створення запису доставки.
• State — Pending, Success, Failed або Dead.
• HTTP — статус відповіді, кількість спроб, тривалість і час наступної спроби, якщо застосовно.
• Subscriber — електронна адреса підписника, якщо подія пов’язана з підписником.
• Delivery — тип події, ідентифікатор події та ідентифікатор доставки.
• Actions — Replay, якщо доставка відповідає вимогам.

Якщо HTTP-запит не виконувався, у стовпці HTTP показано «No HTTP attempt». Це може статися, коли Maildroppa відхиляє запит до надсилання, наприклад через відсутність секрету підпису або якщо збережене призначення більше не можна безпечно використовувати.

Коли доступно, рядок також показує помилку та фрагмент відповіді, повернутий одержувачем. Не повертайте секрети або конфіденційні персональні дані в тілі відповіді вебхука, оскільки частина цієї відповіді може з’явитися в журналі доставок облікового запису.

Стани доставки

Pending означає, що доставка очікує першої спроби або запланованої повторної спроби. «Next retry» відображається, коли заплановано нову спробу.

Success означає, що одержувач повернув відповідь 2xx. Подальша автоматична спроба не потрібна.

Failed означає, що доставка завершилася проблемою, яка не допускає повторення, була відхилена до HTTP-спроби або зупинена до надсилання.

Dead означає, що всі автоматичні спроби через проблему, яка допускає повторення, використано без отримання успішної відповіді.

Зберігання історії

Записи доставок зберігаються обмежений час:

• Успішні робочі доставки: 30 днів
• Невдалі робочі доставки: 90 днів
• Мертві робочі доставки: 90 днів
• Тестові доставки: 30 днів

Зберігайте власні журнали інтеграції, якщо вам потрібна довша історія аудиту. Зберігайте ідентифікатори подій та доставки, але не зберігайте секрети без необхідності.

Повторне відтворення доставки

Натисніть «Replay», коли завершену робочу доставку потрібно спробувати ще раз.

Replay доступний для робочих доставок у стані Success, Failed або Dead. Він недоступний, доки доставка перебуває в стані Pending, а тестові доставки не можна повторно відтворювати.

Повторне відтворення:

• Створює нову доставку Pending.
• Створює новий ідентифікатор доставки.
• Зберігає початковий ідентифікатор події.
• Зберігає початковий тип події та JSON-корисне навантаження.
• Використовує початкову збережену URL-адресу призначення та знімок власних заголовків.
• Використовує поточний секрет підпису під час підготовки нового запиту.

Replay не створює корисне навантаження заново з поточних даних підписника. Він повторно надсилає початковий знімок події. Це робить повторне відтворення придатним для аудиту та не дає історичній події непомітно змінити значення.

Одночасно може перебувати в стані Pending лише одне повторне відтворення тієї самої вихідної доставки. Дочекайтеся завершення цього повторного відтворення, перш ніж запитувати інше.

Перед повторним відтворенням переконайтеся, що кінцева точка активна. Якщо кінцева точка неактивна, доставити поставлене в чергу повторне відтворення успішно не вдасться.

Оскільки одержувач міг виконати бізнес-операцію, навіть якщо Maildroppa не отримав успішної відповіді, повторне відтворення може створити дубльований запит. Дедуплікація за ідентифікатором події захищає підключену систему від повторного виконання операції.

Редагування кінцевої точки

Натисніть «Edit», щоб змінити URL-адресу, вибір подій, власні заголовки або активний стан.

Перед збереженням:

1. Переконайтеся, що нова URL-адреса вже доступна.
2. Залишайте збережені значення заголовків порожніми, якщо вони мають залишитися без змін.
3. Введіть нове значення для кожного перейменованого заголовка.
4. Перевірте вибір подій, щоб випадково не видалити потрібні сповіщення.
5. Збережіть і надішліть новий тестовий вебхук.

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

Деактивація кінцевої точки

Використовуйте перемикач On/Off, коли хочете призупинити інтеграцію, не видаляючи її конфігурацію та історію.

Коли кінцеву точку вимкнено:

• Нові події більше не ставляться для неї в чергу.
• Доставки Pending, які ще не були захоплені для надсилання, позначаються як Failed.
• Test вимикається.
• Кінцева точка залишається доступною для редагування та подальшої активації.

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

Події, пропущені під час неактивності кінцевої точки, не заповнюються заднім числом після її повторного ввімкнення.

Видалення кінцевої точки

Натисніть «Delete» і підтвердьте попередження, якщо кінцева точка більше не має існувати.

Видалення прибирає кінцеву точку зі сторінки, зупиняє майбутні доставки подій і завершує помилкою доставки Pending, які ще не були захоплені для надсилання.

Delete — не спосіб тимчасово призупинити роботу. Використовуйте перемикач On/Off, якщо конфігурація або видима історія можуть знову знадобитися.

Перед видаленням запишіть усі ідентифікатори подій або доставки, які ще потрібні для аудиту інтеграції.

Усунення несправностей

Кінцеву точку не можна зберегти

Перевірте, що:

• URL-адреса починається з https://.
• URL використовує загальнодоступне ім’я хоста та порт 443.
• URL не містить змінних, даних для входу або фрагмента.
• Вибрано принаймні одну подію.
• Кожен власний заголовок має унікальну назву та значення.
• Зарезервовані заголовки Maildroppa та HTTP не використовуються як власні назви.

Test вимкнено

Test доступний лише для активної кінцевої точки. Увімкніть кінцеву точку або відредагуйте її та виберіть «Active», потім збережіть перед тестуванням.

Тест не показує HTTP-спроби

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

Запит може бути відхилено до надсилання, якщо його секрет, URL, власні заголовки або перевірка безпеки призначення недійсні.

Одержувач повертає 401 або 403

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

Також перевірте, чи не плутає одержувач власні облікові дані API з підписом Maildroppa. Власний заголовок авторизації та X-Maildroppa-Signature мають різні цілі й можуть перевірятися незалежно.

Одержувач повертає перенаправлення

Maildroppa не переходить за перенаправленнями. Замініть URL кінцевої точки на кінцеву загальнодоступну HTTPS-адресу та протестуйте знову.

Підпис не збігається

Переконайтеся, що одержувач:

• Використовує поточний секрет підпису.
• Використовує точне значення X-Maildroppa-Timestamp.
• Підписує <timestamp>.<raw request body>.
• Використовує HMAC-SHA256 і вивід у нижньому регістрі шістнадцяткової системи.
• Порівнює повне значення, включно з v1=.
• Виконує порівняння до того, як розбір JSON змінить тіло.

Та сама подія надходить більше одного разу

Це може статися після переривання мережі, повторної спроби або ручного повторного відтворення. Для систем доставки вебхуків нормально забезпечувати доставку щонайменше один раз, а не рівно один раз.

Використовуйте ідентифікатор події як ключ ідемпотентності. Повертайте відповідь 2xx, коли вже оброблений ідентифікатор події надходить повторно і додаткові дії не потрібні.

Доставка очікує

Перегляньте «Next retry» у стовпці HTTP. Повторна спроба з кодом 408, 429, 5xx або тимчасовою мережевою помилкою залишається Pending до наступної запланованої спроби.

Натисніть «Refresh» після часу повторної спроби, щоб завантажити найновіший стан.

Доставка стала мертвою

Усі автоматичні спроби використано. Спочатку виправте одержувача, переконайтеся, що кінцева точка активна, надішліть тестовий вебхук, а потім використайте Replay для робочої доставки.

Рекомендований контрольний список для робочого середовища

Перед тим як покладатися на кінцеву точку в робочому середовищі, переконайтеся в такому:

1. Одержувач використовує стабільну загальнодоступну HTTPS-адресу з дійсним сертифікатом.
2. Секрет підпису зберігається поза вихідним кодом.
3. Підпис перевіряється щодо незміненого необробленого тіла.
4. Старі мітки часу відхиляються відповідно до задокументованого допуску.
5. Одержувач зберігає та дедуплікує ідентифікатори подій.
6. Одержувач записує ідентифікатори подій і доставки для трасування.
7. Повільна обробка відбувається після надійного прийняття події.
8. Відповідь 2xx повертається лише для прийнятих подій.
9. Власні облікові дані зберігаються в заголовках, а не в URL-адресі.
10. Вибрано лише потрібні типи подій.
11. Тестовий вебхук успішний і правильно відображається в історії доставок.
12. Моніторинг сповіщає вас, коли робочі доставки починають повертати помилки.

Завдяки цим заходам безпеки сторінка Webhooks забезпечує обидві складові надійної інтеграції: безпечну доставку подій до вашої програми та зрозумілу операційну історію в Maildroppa.