Конфигуриране на Webhooks

Published: 16 юли 2026 г. · Last updated: 21 юли 2026 г. · By Marcus Biel

Webhooks позволяват на Maildroppa да уведомява друго приложение, когато във вашия акаунт се случи нещо важно.

Вместо многократно да питате Maildroppa дали даден абонат е създаден, актуализиран, отписан или му е присвоен етикет, приложението ви може да получи HTTPS заявка малко след настъпването на събитието.

Страницата Webhooks е централното място за тази интеграция на ниво акаунт. Можете да създадете няколко крайни точки, да изберете събитията, които всяка крайна точка получава, да добавите заглавки за удостоверяване, да тествате връзката, да преглеждате опитите за доставка и при необходимост да повторите събитие от продукционна среда.

Как работят Webhooks на ниво акаунт

Webhook на ниво акаунт следва този процес:

1. В Maildroppa се случва събитие, например създава се абонат.
2. Maildroppa намира всяка активна крайна точка, абонирана за това събитие.
3. Maildroppa създава една доставка за всяка съвпадаща крайна точка.
4. JSON payload-ът се подписва с Signing secret на вашия акаунт за webhook-и.
5. Maildroppa изпраща HTTPS заявка POST към запазения URL адрес на крайната точка.
6. Крайната ви точка проверява подписа, съхранява или обработва събитието и връща HTTP отговор.
7. Maildroppa записва резултата в Delivery history и автоматично повтаря временните неуспешни опити.

Ако няколко крайни точки са абонирани за едно и също събитие, всяка получава собствена доставка. Бизнес събитието има един и същ Event ID за всички тях, докато всяка доставка има собствен Delivery ID.

Webhook-ите на ниво акаунт се различават от стъпка „Send a webhook“ в Automation. Webhook-ите на акаунт следят избрани събития в акаунта в Maildroppa. Automation webhook се изпраща само когато абонат достигне конкретната стъпка. И двата вида използват Signing secret на акаунта, така че ротацията на тайната засяга всеки получател на изходящи webhook-и, който проверява подписите на Maildroppa.

Отваряне на страницата Webhooks

Отворете „Settings“, разгънете „Developers“ и изберете „Webhooks“.

Страницата съдържа три основни области:

• Signing secret
• Endpoints
• Delivery history за избраната крайна точка

Когато имате повече от една крайна точка, изберете ред на крайна точка, за да покажете нейната Delivery history. Ако не сте избрали крайна точка изрично, Maildroppa показва историята на първата крайна точка в списъка.

Преди да създадете крайна точка

Подгответе получател на вашия сървър, преди да конфигурирате Maildroppa. Получателят трябва да:

• Бъде достъпен чрез публичен HTTPS URL.
• Приема POST заявки с тяло application/json.
• Запазва необработеното тяло на заявката, докато подписът на Maildroppa бъде проверен.
• Връща статус 2xx само след като събитието е безопасно прието.
• Обработва повторните доставки идемпотентно чрез Event ID.
• Отговаря бързо, вместо да извършва бавни операции по време на заявката.

Надежден подход е да проверите заявката, да съхраните Event ID и payload-а в устойчива опашка или база данни, да върнете 200 или 204 и след това да обработите бизнес действието.

Не излагайте компютър за разработка, локален мрежов адрес или незащитен скрипт като продукционен получател на webhook-и. Maildroppa приема само публични HTTPS цели и проверява дестинацията отново при изпращане на доставка.

Стъпка 1: Генериране на Signing secret

Всяка заявка на Maildroppa webhook е подписана. Получателят ви използва Signing secret, за да провери, че заявката е създадена от Maildroppa и че тялото не е променено при преноса.

В горната част на страницата панелът Signing secret показва едно от следните състояния:

• Missing — Все още няма Signing secret.
• Ready — Конфигуриран е Signing secret.
• Loading — Maildroppa извлича текущия статус.

Щракнете върху „Generate secret“, когато статусът е Missing.

Maildroppa показва новата тайна незабавно. Тя започва с whsec_. Щракнете върху „Copy“ и я съхранете в мениджър на тайни или защитена конфигурация на средата, използвана от получателя ви.

Пълната стойност се показва само непосредствено след генериране или ротация. Когато презаредите или напуснете страницата, Maildroppa показва само, че съществува тайна и кога е била актуализирана за последно. Тайната не се показва отново.

Ако загубите тайната

Ако получателят вече не разполага с текущата тайна, щракнете върху „Rotate secret“ и запазете новопоказаната стойност.

Ротацията незабавно заменя предишната тайна. Maildroppa не запазва и двете стойности за преходен период. Актуализирайте всеки получател, който използва тази тайна на акаунта, преди да изпращате нови тестове или да разчитате на продукционни доставки.

Новите доставки, планираните повторни опити, тестовете и повторенията се подписват с текущата тайна към момента на HTTP заявката. Това означава, че доставка, създадена преди ротацията, все пак може да бъде подписана с новата тайна, когато бъде направен опит за изпращането ѝ след това.

Третирайте тайната като парола

Не поставяйте Signing secret в код на браузъра, публично хранилище, URL, страница с грешка или обикновен лог на приложението.

Само сървърният получател се нуждае от тайната. Ако смятате, че тя е била разкрита, ротирайте я и незабавно актуализирайте всички получатели.

Проверка на подписа на Webhook

Всяка заявка съдържа следните заглавки на 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. Подписаното съдържание е timestamp-ът, последван от точка, последван от точното необработено JSON тяло на заявката:

<timestamp>.<raw request body>

Използвайте Signing secret като 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);
}

След като проверите подписа, сравнете и timestamp-а с времето на сървъра. Отхвърляйте заявки извън кратък толеранс, избран за вашата инфраструктура, например пет минути. Това намалява риска прихваната валидна заявка да бъде повторена много по-късно.

Анализирайте и обработвайте JSON само след успешното преминаване и на двете проверки.

Чести причини за грешки в подписа

Подписът обикновено е невалиден поради една от следните причини:

• Получателят използва стара тайна след ротация.
• Middleware е анализирал или променил JSON-а, преди да бъде изчислен подписът.
• Получателят подписва само тялото и пропуска <timestamp>..
• Timestamp-ът се третира като форматирана дата вместо като точната стойност от заглавката.
• Префиксът v1= е пропуснат при сравнението.
• Изчисленият HMAC е кодиран по различен начин вместо като шестнадесетичен текст с малки букви.

Записвайте Event ID и Delivery ID при неуспешна проверка, но никога не записвайте Signing secret или чувствителни стойности на персонализирани заглавки.

Стъпка 2: Добавяне на крайна точка

Щракнете върху „Add endpoint“ в секцията Endpoints.

Редакторът съдържа четири части:

• Endpoint URL
• Events
• Custom headers
• Active status

Новите крайни точки започват като Active, а всички събития, показани в редактора, първоначално са избрани. Прегледайте избора, преди да запазите, за да получава получателят само известията, от които действително се нуждае.

Конфигуриране на Endpoint URL

Въведете пълния публичен URL, който трябва да получава заявките на Maildroppa, например:

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

URL адресът трябва да отговаря на следните изисквания:

• Трябва да използва https://.
• Трябва да съдържа валидно публично име на хост.
• Може да бъде дълъг до 2 048 знака.
• Не може да съдържа template variables с { или }.
• Не може да съдържа потребителско име или парола преди името на хоста.
• Не може да съдържа URL фрагмент, започващ с #.
• Трябва да използва стандартния HTTPS порт 443.
• Не може да използва localhost, необработен IP адрес или име на хост, което сочи към блокирана частна или резервирана мрежа.

Параметрите на заявката се поддържат, но не поставяйте API ключове или други тайни в URL. URL адресите се виждат в списъка с крайни точки и данните за доставките. Вместо това използвайте Custom header за идентификационни данни.

Maildroppa не следва пренасочвания. Запазете крайната HTTPS дестинация, а не URL, който връща 301, 302, 307 или 308.

Името на хоста на дестинацията се разрешава отново преди изпращане. Име на хост, което по-късно сочи към частен или блокиран адрес, се отхвърля, дори да е било валидно при запазването на крайната точка.

Избор на събития

Изберете поне едно събитие. Крайната точка получава само типовете събития, избрани в редактора ѝ.

Страницата предлага следните опции за събития:

Subscriber Created — subscriber.created

Изпраща се, когато в акаунта на Maildroppa бъде създаден абонат.

Използвайте това събитие, за да създадете съответния контакт в CRM, платформа за клиентски данни, вътрешна база данни или друга система с контрол на разрешенията.

Не приемайте това събитие като доказателство, че всяко регистриране е завършило Double Opt-in. Статусът на абоната в payload-а описва текущото състояние.

Subscriber Updated — subscriber.updated

Изпраща се, когато вградената информация за абоната или стойностите на персонализираните полета се променят.

Използвайте пълния обект на абоната в payload-а като текущото представяне на абоната в Maildroppa. Не приемайте, че се е променило само едно конкретно свойство.

Присвояването и премахването на етикети имат собствени типове събития, за да могат да бъдат обработвани отделно.

Subscriber Unsubscribed — subscriber.unsubscribed

Изпраща се, когато абонатът премине в състояние unsubscribed чрез действие за отписване.

Използвайте това събитие, за да потиснете контакта в свързаните системи. Не абонирайте автоматично човека отново, защото друга система все още го маркира като активен.

Tag Added — subscriber.tag_added

Изпраща се, когато на абонат бъде присвоен етикет.

Payload-ът съдържа абоната и етикета, свързан с конкретната промяна.

Tag Removed — subscriber.tag_removed

Изпраща се, когато етикет бъде премахнат от абонат.

Payload-ът съдържа актуализирания абонат и премахнатия етикет. Премахнатият етикет се предоставя отделно, въпреки че вече не присъства в текущия tags масив на абоната.

Form Submitted — form.submitted

Изпраща се, когато посетител изпрати регистрационна форма на Maildroppa.

Третирайте това като сигнал за изпращане на форма, а не като потвърждение, че Double Opt-in е завършен. Всеки работен процес, който изисква потвърден абонамент, трябва да продължи да спазва текущия статус на абоната и процеса на потвърждение.

Използвайте отделни крайни точки, когато отговорностите се различават

Можете да изпращате различни събития към различни системи. Например:

• Изпращайте събитията за абонати и етикети към CRM.
• Изпращайте събитията за отписване към услуга за потискане.
• Изпращайте събитията за изпращане на форма към аналитичен pipeline.

Отделните крайни точки намаляват ненужния трафик и улесняват диагностицирането на грешки. Всяка крайна точка има собствен избор на събития, URL, персонализирани заглавки, активен статус, тестове и Delivery history.

Добавяне на Custom headers

Персонализираните заглавки са по избор. Използвайте ги, когато получателят изисква API ключ, bearer token, идентификатор на клиент или друга фиксирана заглавка.

Щракнете върху „Add header“, след което въведете Header name и Header value. Подходящи примери са:

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 запазва съхранена тайна само докато първоначалното ѝ име на заглавка остане непроменено.

Премахването на ред с заглавка премахва тази заглавка от бъдещите доставки след запазване на крайната точка.

Стойностите на персонализираните заглавки се третират като чувствителни в съхранената информация за заявката. Те се маскират, вместо да се показват в Delivery history.

Задаване на Endpoint като Active или Inactive

Оставете „Active“ избрано, когато крайната точка е готова да получава събития незабавно.

Премахнете избора, когато искате да запазите конфигурацията, без да започвате доставки. По-късно можете да активирате крайната точка от списъка с крайни точки.

Неактивна крайна точка:

• Не получава нововъзникнали събития.
• Не може да изпрати Test webhook.
• Остава видима и редактируема.
• Запазва достъпната си съществуваща Delivery history.

Активирането на крайна точка не попълва обратно събитията, възникнали, докато е била неактивна.

Щракнете върху „Save“, когато URL адресът, изборът на събития, заглавките и статусът са правилни.

Разбиране на списъка с крайни точки

Всеки ред на крайна точка показва:

• URL адреса на дестинацията.
• Значка Active или Inactive.
• Абонираните типове събития.
• Броя на персонализираните заглавки.
• Часа на последната актуализация на крайната точка.

Наличните действия са:

• On/Off — Активира или деактивира крайната точка.
• Test — Изпраща един незабавен тестов request към активна крайна точка.
• Edit — Променя URL адреса, събитията, заглавките или активния статус.
• Delete — Премахва конфигурацията на крайната точка окончателно след потвърждение.

Изберете основната част на реда, за да отворите Delivery history на тази крайна точка под списъка.

Как запазените промени засягат съществуващите доставки

Събитие на акаунта създава доставка със snapshot на URL адреса на крайната точка, payload-а и персонализираните заглавки към този момент.

Редактирането на URL адреса или персонализираните заглавки засяга новосъздадените доставки. Доставка, която вече е била поставена на опашка, запазва първоначалната си дестинация и съхранената конфигурация на заглавките.

Промяната на избраните събития също засяга само събитията, възникнали след това. Maildroppa не създава доставки със задна дата за типове събития, които не са били избрани при настъпването на събитието.

Signing secret е различен: той се прочита при подготовката на HTTP заявката. Затова чакаща доставка или повторение може да използва новоротиран Signing secret, дори payload-ът и snapshot-ът на крайната точка да са създадени по-рано.

Тестване на крайна точка

Щракнете върху „Test“ на активна крайна точка, след като получателят и Signing secret са готови.

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

Тестовият payload използва типа събитие 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."
  }
}

Генерираните ID стойности и timestamp са различни за всеки реален тест.

Тестът прави точно един HTTP опит. Тестовите доставки не се поставят в продукционния график за повторни опити и не могат да бъдат повторени.

След приключване на заявката панелът с резултата показва:

• Test success или Test failed
• Event ID
• HTTP статус, когато е получен отговор
• Продължителност
• Delivery ID
• Информация за грешка, когато е налична
• Извадка от отговора, когато получателят е върнал тяло

Тестът се появява и в Delivery history със значка Test. Използвайте филтъра „Test“, за да покажете само тестови заявки.

Разбиране на продукционния payload

Продукционните събития на акаунта използват общ JSON envelope:

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

Свойствата на най-високо ниво означават:

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

Маршрутизирайте събитията по точната стойност на type. Игнорирайте допълнителните свойства, от които интеграцията ви не се нуждае, така че съвместимите допълнения към payload-а да не повредят получателя.

Payload на събитие за абонат

Събитията за абонати съдържат текущото представяне на абоната в 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, когато няма стойност, затова получателят ви трябва да следва схемата на payload-а, вместо да приема, че всяка незадължителна профилна стойност присъства.

Payload на събитие за етикет

Събитията за етикети съдържат както абоната, така и етикета, причинил събитието:

{
  "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 на абоната вече не го съдържа.

Event ID, Delivery ID и идемпотентност

Event ID и Delivery ID имат различни цели.

Event ID

Event ID идентифицира бизнес събитието. Той се появява в:

• Свойството id на най-високо ниво в payload-а.
• Заглавката на заявката X-Maildroppa-Event-Id.
• Delivery history.

Едно и също събитие може да бъде изпратено към няколко абонирани крайни точки. Тези доставки споделят Event ID.

Повторните опити и ръчните повторения също запазват оригиналния Event ID. Съхранявайте обработените Event ID стойности и направете бизнес действието идемпотентно, така че повторна заявка да не създава дублирани контакти, да повтаря необратимо действие или да прилага една и съща промяна два пъти.

Delivery ID

Delivery ID идентифицира един запис за доставка. Той се появява в:

• Заглавката на заявката X-Maildroppa-Delivery-Id.
• Delivery history.

Всяка доставка към крайна точка има собствен Delivery ID. Ръчното повторение създава нов Delivery ID, като запазва оригиналния Event ID.

Използвайте Delivery ID за техническо проследяване и поддръжка. Използвайте Event ID за дедупликация на ниво бизнес логика.

Връщане на правилния HTTP отговор

Maildroppa класифицира отговорите по следния начин:

• Всеки отговор 2xx маркира доставката като успешна.
• Отговорите 408 Request Timeout, 429 Too Many Requests и 5xx са временни грешки и могат да бъдат повторени.
• Мрежовите грешки, които могат да бъдат временни, се повтарят.
• Пренасочванията и другите отговори 3xx не се следват и се третират като окончателни грешки.
• Другите отговори 4xx се третират като окончателни грешки и не се повтарят.

Връщайте 200, 202 или 204 само когато събитието е безопасно прието. Ако обработката отнема време, първо съхранете събитието и върнете успешен отговор, преди да извършите по-бавната работа асинхронно.

Не връщайте пренасочване към друг URL за webhook. Конфигурирайте крайния URL в Maildroppa.

Автоматичен график за повторни опити

Продукционните доставки могат да направят до седем HTTP опита.

След грешка, подлежаща на повторен опит, Maildroppa планира следващия опит със следните закъснения:

1. След опит 1: 1 минута
2. След опит 2: 5 минути
3. След опит 3: 30 минути
4. След опит 4: 2 часа
5. След опит 5: 12 часа
6. След опит 6: 24 часа

Ако опит 7 все още получи грешка, подлежаща на повторен опит, доставката става Dead и повече автоматични опити не се планират.

Графикът се измерва от отделните неуспешни опити. Реалното време на доставка може да бъде малко по-късно, тъй като доставките се обработват асинхронно и също са обект на ограничения за защита на системата.

Когато е възможно, отстранете временния проблем с получателя преди показаното време „Next retry“. Ако автоматичните опити са приключили, използвайте Replay, след като получателят отново работи нормално.

Разбиране на Delivery history

Delivery history принадлежи на текущо избраната крайна точка. URL адресът на крайната точка се показва в заглавката на секцията, за да можете да потвърдите коя история преглеждате.

Използвайте следните филтри:

• All — Показва продукционни и тестови доставки.
• Production — Показва само доставки на активни събития.
• Test — Показва само ръчни тестове.

Щракнете върху „Refresh“, за да извлечете най-новото състояние. Не е необходимо историята да остава отворена, докато Maildroppa изпраща или повтаря доставка.

Страницата показва последните 50 съвпадащи доставки за избрания филтър.

Колони в Delivery

Всеки ред съдържа:

• Created — Кога е създаден записът за доставката.
• State — Pending, Success, Failed или Dead.
• HTTP — Статус на отговора, брой опити, продължителност и време за следващия опит, когато е приложимо.
• Subscriber — Имейлът на абоната, когато събитието е свързано с абонат.
• Delivery — Тип събитие, Event ID и Delivery ID.
• Actions — Replay, когато доставката отговаря на условията.

Ако не е направена HTTP заявка, колоната HTTP показва „No HTTP attempt“. Това може да се случи, когато Maildroppa отхвърли заявката преди изпращане, например защото Signing secret липсва или запазената дестинация вече не може да бъде използвана безопасно.

Когато е налично, редът показва и Error и Response excerpt, върнат от получателя. Не връщайте тайни или чувствителни лични данни в тялото на отговора на webhook-а, тъй като част от този отговор може да се появи в лога за доставки на акаунта.

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

Pending означава, че доставката изчаква първия си опит или планиран повторен опит. „Next retry“ се показва, когато е планиран следващ опит.

Success означава, че получателят е върнал отговор 2xx. Не е необходим допълнителен автоматичен опит.

Failed означава, че доставката е приключила с проблем, който не подлежи на повторен опит, била е отхвърлена преди HTTP опит или е била спряна, преди да бъде изпратена.

Dead означава, че всички автоматични опити за проблем, подлежащ на повторен опит, са изчерпани, без да бъде получен успешен отговор.

Запазване на историята

Записите за доставки се запазват за ограничен период:

• Успешни продукционни доставки: 30 дни
• Неуспешни продукционни доставки: 90 дни
• Dead продукционни доставки: 90 дни
• Тестови доставки: 30 дни

Поддържайте собствени логове на интеграцията, когато ви е необходима по-дълга история за одит. Съхранявайте Event ID и Delivery ID, но избягвайте ненужното съхраняване на тайни.

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

Щракнете върху „Replay“, когато завършена продукционна доставка трябва да бъде изпратена отново.

Replay е достъпно за продукционни доставки със състояние Success, Failed или Dead. Не е достъпно, докато доставката е Pending, а тестовите доставки не могат да бъдат повторени.

Повторението:

• Създава нова Pending доставка.
• Създава нов Delivery ID.
• Запазва оригиналния Event ID.
• Запазва оригиналния тип събитие и JSON payload.
• Използва оригиналния запазен URL адрес на целта и snapshot на персонализираните заглавки.
• Използва текущия Signing secret при подготовката на новата заявка.

Replay не изгражда отново payload-а от текущите данни на абоната. То изпраща отново оригиналния snapshot на събитието. Това прави повторението проследимо и предотвратява незабелязаната промяна на смисъла на историческо събитие.

Само едно повторение на една и съща изходна доставка може да бъде Pending едновременно. Изчакайте това повторение да приключи, преди да заявите ново.

Уверете се, че крайната точка е Active, преди да повторите доставката. Ако крайната точка е неактивна, поставеното на опашка повторение няма да може да бъде доставено успешно.

Тъй като получателят може да е завършил бизнес действието, дори когато Maildroppa не е получил успешния му отговор, повторението може да доведе до дублирана заявка. Дедупликацията по Event ID защитава свързаната система от повторно изпълнение на действието.

Редактиране на крайна точка

Щракнете върху „Edit“, за да промените URL адреса, избора на събития, персонализираните заглавки или активния статус.

Преди запазване:

1. Потвърдете, че новият URL вече е достъпен.
2. Оставете запазените стойности на заглавките празни, когато трябва да останат непроменени.
3. Въведете нова стойност за всяка преименувана заглавка.
4. Прегледайте избора на събития, за да не премахнете случайно необходимите известия.
5. Запазете и изпратете нов Test webhook.

Помнете, че доставките на опашка запазват съществуващия си URL и snapshot на персонализираните заглавки. Тествайте новата конфигурация за бъдещи доставки, вместо да приемате, че тя променя по-стара заявка на опашка.

Деактивиране на крайна точка

Използвайте превключвателя On/Off, когато искате да поставите интеграцията на пауза, без да изтривате конфигурацията и историята ѝ.

Когато крайната точка бъде изключена:

• Новите събития вече не се поставят на опашка за нея.
• Pending доставките, които още не са били заявени за изпращане, се маркират като Failed.
• Test е деактивирано.
• Крайната точка остава достъпна за редактиране и последващо активиране.

Заявка, която вече е в процес на изпращане в момента на деактивиране, може все пак да завърши. Проверете Delivery history след изключването на крайната точка, ако това разграничение е важно за интеграцията ви.

Събитията, пропуснати, докато крайната точка е неактивна, не се попълват обратно, когато я включите отново.

Изтриване на крайна точка

Щракнете върху „Delete“ и потвърдете предупреждението, когато крайната точка вече не трябва да съществува.

Изтриването премахва крайната точка от страницата, спира бъдещите доставки на събития и маркира като Failed чакащите доставки, които още не са били заявени за изпращане.

Delete не е начин за временно поставяне на пауза. Използвайте превключвателя On/Off, когато може отново да ви потрябва конфигурацията или видимата ѝ история.

Преди изтриване запишете Event ID или Delivery ID, които все още са ви необходими за одита на интеграцията.

Отстраняване на неизправности

Крайната точка не може да бъде запазена

Проверете дали:

• URL адресът започва с https://.
• URL адресът използва публично име на хост и порт 443.
• URL адресът не съдържа променливи, информация за вход или фрагмент.
• Избрано е поне едно събитие.
• Всяка Custom header има уникално име и стойност.
• Запазените заглавки на Maildroppa и HTTP не се използват като персонализирани имена.

Test е деактивиран

Test е достъпен само за Active крайна точка. Включете крайната точка или я редактирайте и изберете „Active“, след което запазете, преди да тествате.

Test показва, че няма HTTP опит

Генерирайте Signing secret, ако статусът е Missing. Проверете също дали името на хоста на дестинацията е публично и все още се разрешава правилно.

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

Получателят връща 401 или 403

Проверете запазеното име на Custom header и идентификационните данни. Редактирайте крайната точка и въведете стойността отново, ако се е променила.

Проверете също дали получателят не бърка собствените си API идентификационни данни с подписа на Maildroppa. Персонализираната Authorization заглавка и X-Maildroppa-Signature имат различни цели и могат да се проверяват независимо.

Получателят връща пренасочване

Maildroppa не следва пренасочвания. Заменете URL адреса на крайната точка с крайния публичен HTTPS URL и тествайте отново.

Подписът не съвпада

Потвърдете, че получателят:

• Използва текущия Signing secret.
• Използва точната стойност на X-Maildroppa-Timestamp.
• Подписва <timestamp>.<raw request body>.
• Използва HMAC-SHA256 и шестнадесетичен резултат с малки букви.
• Сравнява пълната стойност, включително v1=.
• Извършва сравнението, преди анализът на JSON да промени тялото.

Едно и също събитие пристига повече от веднъж

Това може да се случи след прекъсване на мрежата, повторен опит или ръчно повторение. Нормално е системите за доставка на webhook-и да осигуряват доставка поне веднъж, а не доставка точно веднъж.

Използвайте Event ID като idempotency key. Върнете отговор 2xx, когато получите вече обработен Event ID и не е необходимо допълнително действие.

Доставка е Pending

Проверете „Next retry“ в колоната HTTP. Повторима грешка 408, 429, 5xx или временна мрежова грешка остават Pending до следващия планиран опит.

Щракнете върху „Refresh“ след времето за повторен опит, за да заредите най-новото състояние.

Доставка е Dead

Всички автоматични опити са изчерпани. Първо отстранете проблема с получателя, уверете се, че крайната точка е Active, изпратете Test webhook и след това използвайте Replay за продукционната доставка.

Препоръчителен продукционен checklist

Преди да разчитате на крайна точка в продукция, потвърдете всичко от следното:

1. Получателят използва стабилен публичен HTTPS URL с валиден сертификат.
2. Signing secret се съхранява извън изходния код.
3. Подписът се проверява спрямо непромененото необработено тяло.
4. Старите timestamp стойности се отхвърлят според документиран толеранс.
5. Получателят съхранява и дедупликира Event ID стойностите.
6. Получателят записва Event ID и Delivery ID за проследяване.
7. Бавната обработка се извършва, след като събитието бъде прието трайно.
8. Отговор 2xx се връща само за приети събития.
9. Персонализираните идентификационни данни се съхраняват в заглавки, а не в URL.
10. Избрани са само необходимите типове събития.
11. Test webhook завършва успешно и се появява правилно в Delivery history.
12. Наблюдението ви предупреждава, когато продукционните доставки започнат да връщат грешки.

С тези предпазни мерки страницата Webhooks осигурява и двете страни на надеждната интеграция: сигурна доставка на събития към приложението ви и ясна оперативна история в Maildroppa.