Конфигурирање веб-куки

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

Веб-куките му овозможуваат на Maildroppa да извести друга апликација кога ќе се случи нешто важно во вашата сметка.

Наместо постојано да го прашувате Maildroppa дали претплатникот е создаден, ажуриран, отпишан или му е доделена ознака, вашата апликација може да прими HTTPS-барање кратко по настанувањето на настанот.

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

Како функционираат веб-куките на ниво на сметка

Веб-куката на сметката го следи овој процес:

1. Во Maildroppa се случува настан, како што е создавање претплатник.
2. Maildroppa ја наоѓа секоја активна крајна точка претплатена на тој настан.
3. Maildroppa создава една испорака за секоја соодветна крајна точка.
4. JSON-податоците се потпишуваат со Signing secret на вашата сметка.
5. Maildroppa испраќа HTTPS-барање POST до зачуваната URL-адреса на крајната точка.
6. Вашата крајна точка го проверува потписот, го зачувува или обработува настанот и враќа HTTP-одговор.
7. Maildroppa го евидентира резултатот во историјата на испораки и автоматски ги повторува привремените неуспеси.

Ако повеќе крајни точки се претплатени на истиот настан, секоја крајна точка добива сопствена испорака. Деловниот настан има ист Event ID за сите нив, додека секоја испорака има сопствен Delivery ID.

Веб-куките на сметката се разликуваат од чекорот „Send a webhook“ во Automation. Веб-куките на сметката слушаат избрани настани на сметката низ Maildroppa. Automation веб-куката се испраќа само кога претплатникот ќе стигне до конкретниот чекор. И двете го користат Signing secret на сметката, па ротирањето на тајната влијае врз секој надворешен примач што ги проверува потписите на Maildroppa.

Отворање на страницата Webhooks

Отворете „Settings“, проширете „Developers“ и изберете „Webhooks“.

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

• Signing secret
• Endpoints
• Историја на испораки за избраната крајна точка

Кога имате повеќе од една крајна точка, изберете ред со крајна точка за да ја прикажете нејзината историја на испораки. Ако не сте избрале крајна точка експлицитно, Maildroppa ја прикажува историјата на првата крајна точка во списокот.

Пред да создадете крајна точка

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

• Да биде достапен преку јавна HTTPS URL-адреса.
• Да прифаќа POST-барања со тело application/json.
• Да го зачува необработеното тело на барањето додека не се провери потписот на Maildroppa.
• Да враќа статус 2xx само откако настанот безбедно ќе биде прифатен.
• Повторените испораки да ги обработува идемпотентно со користење на Event ID.
• Да одговара брзо, наместо да извршува бавни операции за време на барањето.

Сигурен образец е да го проверите барањето, да ги зачувате Event ID и податоците во трајна редица или база на податоци, да вратите 200 или 204, а деловното дејство да го обработите подоцна.

Не изложувајте развоен компјутер, локална мрежна адреса или незаштитена скрипта како продукциски примач на веб-куки. Maildroppa прифаќа само јавни HTTPS-цели и повторно ја проверува дестинацијата кога се испраќа испорака.

Чекор 1: Генерирање Signing secret

Секое барање за веб-кука од Maildroppa е потпишано. Вашиот примач го користи 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-адреса, страница со грешка или обичен дневник на апликацијата.

Само серверскиот примач ја има потребната тајна. Ако сметате дека е откриена, ротирајте ја и веднаш ажурирајте ги сите примачи.

Проверка на потпис на веб-кука

Секое барање ги содржи следниве заглавја на 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>

Користете го 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);
}

По проверката на потписот, споредете го и времето со времето на вашиот сервер. Одбивајте барања надвор од кратка толеранција избрана за вашата инфраструктура, како пет минути. Така се намалува ризикот валидно снимено барање да биде повторно испратено многу подоцна.

Анализирајте ги и обработувајте ги JSON-податоците само откако ќе поминат двете проверки.

Вообичаени причини за грешки со потписот

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

• Примачот користи стара тајна по ротирањето.
• Middleware го анализирал или изменил JSON-от пред пресметувањето на потписот.
• Примачот го потпишува само телото и изоставува <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 знаци.
• Не смее да содржи шаблонски променливи со { или }.
• Не смее да содржи корисничко име или лозинка пред името на хостот.
• Не смее да содржи фрагмент на 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. Статусот на претплатникот во податоците го опишува тековниот статус.

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.

Третирајте го ова како сигнал за поднесување формулар, а не како потврда дека Double Opt-in е завршен. Секој работен тек што бара потврдена претплата мора и понатаму да го почитува тековниот статус на претплатникот и процесот на потврда.

Користете одделни крајни точки кога одговорностите се разликуваат

Можете да испраќате различни настани до различни системи. На пример:

• Испраќајте настани за претплатници и ознаки до CRM.
• Испраќајте настани за отпишување до услуга за потиснување.
• Испраќајте настани за поднесување формулари до аналитички процес.

Одделните крајни точки го намалуваат непотребниот сообраќај и го олеснуваат дијагностицирањето на неуспесите. Секоја крајна точка има сопствен избор на настани, URL-адреса, прилагодени заглавја, активен статус, тестови и историја на испораки.

Додавање прилагодени заглавја

Прилагодените заглавја се опционални. Користете ги кога примачот бара API-клуч, bearer токен, идентификатор на закупец или друго фиксно заглавје.

Кликнете „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 ја задржува зачуваната тајна само додека нејзиното првично име на заглавје останува непроменето.

Отстранувањето на ред со заглавје го отстранува тоа заглавје од идните испораки откако ќе се зачува крајната точка.

Вредностите на прилагодените заглавја се третираат како чувствителни во зачуваните информации за барањата. Тие се маскирани наместо прикажани во историјата на испораки.

Поставување на крајната точка како активна или неактивна

Оставете „Active“ избрано кога крајната точка е подготвена веднаш да прима настани.

Отстранете го изборот кога сакате да ја зачувате конфигурацијата без започнување испораки. Крајната точка можете да ја активирате подоцна од списокот на крајни точки.

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

• Не прима новонастанати настани.
• Не може да испрати Test webhook.
• Останува видлива и може да се уредува.
• Ја задржува постојната историја на испораки.

Активирањето на крајната точка не ги пополнува наназад настаните што се случиле додека била неактивна.

Кликнете „Save“ кога URL-адресата, изборот на настани, заглавјата и статусот се точни.

Разбирање на списокот на крајни точки

Секој ред со крајна точка прикажува:

• URL-адресата на дестинацијата.
• Ознака Active или Inactive.
• Претплатените типови на настани.
• Бројот на прилагодени заглавја.
• Времето кога крајната точка последен пат била ажурирана.

Достапните дејства се:

• On/Off — Ја активира или деактивира крајната точка.
• Test — Испраќа едно непосредно тест-барање до активна крајна точка.
• Edit — Ги менува URL-адресата, настаните, заглавјата или активниот статус.
• Delete — Трајно ја отстранува конфигурацијата на крајната точка по потврда.

Изберете го главниот дел од редот за да ја отворите историјата на испораки на таа крајна точка под списокот.

Како зачуваните промени влијаат врз постојните испораки

Настанот на сметката создава испорака со снимка од URL-адресата на крајната точка, податоците и прилагодените заглавја во тој момент.

Уредувањето на URL-адресата или прилагодените заглавја влијае врз новосоздадените испораки. Испораката што веќе е во редица ја задржува оригиналната дестинација и зачуваната конфигурација на заглавјата.

Промената на избраните настани влијае само врз настаните што ќе се случат потоа. Maildroppa не создава ретроактивни испораки за типови на настани што не биле избрани кога настанот се случил.

Signing secret е различен: се чита кога се подготвува HTTP-барањето. Затоа испорака во чекање или повторно испраќање може да го користи новоротиран Signing secret дури и кога нејзините податоци и снимката на крајната точка биле создадени порано.

Тестирање крајна точка

Кликнете „Test“ на активна крајна точка откако примачот и Signing secret ќе бидат подготвени.

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."
  }
}

Генерираните ID-ја и времето се разликуваат за секој реален тест.

Тестот прави точно еден HTTP-обид. Тест-испораките не се ставаат во продукцискиот распоред за повторни обиди и не можат повторно да се испратат.

Откако барањето ќе заврши, панелот со резултати прикажува:

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

Тестот се појавува и во историјата на испораки со ознака Test. Користете го филтерот „Test“ за да прикажете само тест-барања.

Разбирање на продукциските податоци

Продукциските настани на сметката користат заеднички JSON-обвивка:

{
  "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 — Верзијата на шемата на податоците. Користете ја при одлучување како да го анализирате настанот.
• 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 на претплатникот повеќе не ја содржи.

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

Event ID и Delivery ID служат за различни цели.

Event ID

Event ID го идентификува деловниот настан. Се појавува во:

• Својството id на највисоко ниво во податоците.
• Заглавјето на барањето X-Maildroppa-Event-Id.
• Историјата на испораки.

Истиот настан може да се испрати до повеќе претплатени крајни точки. Тие испораки го делат Event ID.

Повторните обиди и рачните повторни испраќања исто така го задржуваат оригиналниот Event ID. Зачувувајте ги обработените Event ID и направете го деловното дејство идемпотентно за повтореното барање да не создаде дупликат контакти, да повтори неповратно дејство или двапати да ја примени истата промена.

Delivery ID

Delivery ID идентификува еден запис за испорака. Се појавува во:

• Заглавјето на барањето X-Maildroppa-Delivery-Id.
• Историјата на испораки.

Секоја испорака до крајна точка има сопствен 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-адреса на веб-кука. Наместо тоа, конфигурирајте ја конечната 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 откако примачот повторно ќе биде здрав.

Разбирање на историјата на испораки

Историјата на испораки припаѓа на тековно избраната крајна точка. URL-адресата на крајната точка се појавува во заглавјето на делот за да можете да потврдите чија историја ја гледате.

Користете ги овие филтри:

• All — Ги прикажува продукциските и тест-испораките.
• Production — Ги прикажува само испораките на активни настани.
• Test — Ги прикажува само рачните тестови.

Кликнете „Refresh“ за да ја преземете најновата состојба. Историјата не мора да биде отворена додека Maildroppa испраќа или повторува испорака.

Страницата ги прикажува последните 50 соодветни испораки за избраниот филтер.

Колони во испораките

Секој ред содржи:

• 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 вратен од примачот. Не враќајте тајни или чувствителни лични податоци во телото на одговорот на веб-куката бидејќи дел од тој одговор може да се појави во дневникот за испораки на сметката.

Состојби на испорака

Pending значи дека испораката го чека првиот обид или закажаното повторување. „Next retry“ се појавува кога е закажан нов обид.

Success значи дека примачот вратил одговор 2xx. Не е потребен понатамошен автоматски обид.

Failed значи дека испораката завршила со проблем што не може да се повтори, била одбиена пред HTTP-обидот или била запрена пред да може да се испрати.

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

Задржување на историјата

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

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

Чувајте сопствени дневници на интеграцијата кога ви е потребна подолга историја за ревизија. Чувајте ги Event ID и Delivery ID, но избегнувајте непотребно зачувување тајни.

Повторно испраќање испорака

Кликнете „Replay“ кога завршена продукциска испорака треба повторно да се обиде.

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

Replay:

• Создава нова испорака Pending.
• Создава нов Delivery ID.
• Го задржува оригиналниот Event ID.
• Го задржува оригиналниот тип на настан и JSON-податоци.
• Ја користи оригиналната зачувана URL-адреса на целта и снимката на прилагодените заглавја.
• Го користи тековниот Signing secret кога се подготвува новото барање.

Replay не ги обновува податоците од тековните податоци на претплатникот. Повторно ја испраќа оригиналната снимка на настанот. Така повторното испраќање останува проверливо и се спречува историски настан тивко да го промени значењето.

Само едно повторно испраќање на истата изворна испорака може да биде Pending во исто време. Почекајте тоа повторно испраќање да заврши пред да побарате ново.

Проверете дали крајната точка е Active пред повторното испраќање. Ако крајната точка е неактивна, испораката во редица не може успешно да се достави.

Бидејќи примачот можеби го завршил деловното дејство дури и кога Maildroppa не го примил неговиот успешен одговор, Replay може да создаде дупликатно барање. Дедуплицирањето според Event ID го штити поврзаниот систем од повторување на дејството.

Уредување крајна точка

Кликнете „Edit“ за да ги промените URL-адресата, изборот на настани, прилагодените заглавја или активниот статус.

Пред зачувување:

1. Потврдете дека новата URL-адреса е веќе достапна.
2. Оставете ги зачуваните вредности на заглавјата празни кога треба да останат непроменети.
3. Внесете нова вредност за секое преименувано заглавје.
4. Проверете го изборот на настани за потребните известувања да не бидат случајно отстранети.
5. Зачувајте и испратете нов Test webhook.

Запомнете дека испораките во редица ја задржуваат постојната URL-адреса и снимката на прилагодените заглавја. Тестирајте ја новата конфигурација за идните испораки наместо да претпоставувате дека го менува постарото барање во редица.

Деактивирање крајна точка

Користете го прекинувачот On/Off кога сакате да ја паузирате интеграцијата без да ја избришете нејзината конфигурација и историја.

Кога крајната точка е исклучена:

• Новите настани повеќе не се ставаат во редица за неа.
• Испораките Pending што сè уште не биле преземени за испраќање се означуваат како Failed.
• Test е оневозможен.
• Крајната точка останува достапна за уредување и подоцнежно активирање.

Барањето што веќе се обработува во моментот на деактивацијата сè уште може да заврши. Проверете ја историјата на испораки откако ќе ја исклучите крајната точка ако оваа разлика е важна за вашата интеграција.

Настаните пропуштени додека крајната точка е неактивна не се пополнуваат наназад кога повторно ќе ја вклучите.

Бришење крајна точка

Кликнете „Delete“ и потврдете го предупредувањето кога крајната точка повеќе не треба да постои.

Бришењето ја отстранува крајната точка од страницата, ги запира идните испораки на настани и ги означува како Failed испораките Pending што сè уште не биле преземени за испраќање.

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-от да го промени телото.

Истиот настан пристигнува повеќе од еднаш

Ова може да се случи по прекин на мрежата, повторен обид или рачно повторно испраќање. Нормално е системите за испорака на веб-куки да обезбедуваат испорака најмалку еднаш, наместо точно еднаш.

Користете го Event ID како идемпотентен клуч. Вратете одговор 2xx кога повторно ќе се прими веќе обработен Event ID и не е потребно дополнително дејство.

Испораката е Pending

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

Кликнете „Refresh“ по времето за повторен обид за да ја вчитате најновата состојба.

Испораката е Dead

Сите автоматски обиди се искористени. Прво поправете го примачот, проверете дали крајната точка е Active, испратете Test webhook, а потоа користете Replay на продукциската испорака.

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

Пред да се потпрете на крајната точка во продукција, потврдете го следново:

1. Примачот користи стабилна јавна HTTPS URL-адреса со валиден сертификат.
2. Signing secret се чува надвор од изворниот код.
3. Потписот се проверува во однос на неизменетото необработено тело.
4. Старите временски ознаки се одбиваат според документирана толеранција.
5. Примачот ги зачувува и дедуплицира Event ID.
6. Примачот ги евидентира Event ID и Delivery ID за следење.
7. Бавната обработка се одвива откако настанот трајно ќе биде прифатен.
8. Одговор 2xx се враќа само за прифатени настани.
9. Прилагодените акредитиви се чуваат во заглавја наместо во URL-адресата.
10. Избрани се само потребните типови на настани.
11. Test webhook успешно поминува и правилно се појавува во историјата на испораки.
12. Следењето ве известува кога продукциските испораки ќе почнат да враќаат грешки.

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