Configurează webhook-uri

Publicat: 16 iulie 2026 · Ultima actualizare: 12 septembrie 2026 · De Marcus Biel

Webhook-urile permit Maildroppa să notifice o altă aplicație atunci când are loc un eveniment important în cont.

În loc să verifice în mod repetat în Maildroppa dacă un abonat a fost creat, actualizat, dezabonat sau a primit o etichetă, aplicația poate primi o solicitare HTTPS la scurt timp după producerea evenimentului.

Pagina „Webhooks” reunește toate opțiunile pentru această integrare la nivelul contului. Poți crea mai multe endpoint-uri, alege evenimentele pe care le primește fiecare, adăuga antete de autentificare, testa conexiunea, verifica încercările de livrare și retrimite un eveniment din producție atunci când este necesar.

Cum funcționează webhook-urile la nivel de cont

Un webhook la nivel de cont urmează acest proces:

1. În Maildroppa are loc un eveniment, cum ar fi crearea unui abonat.
2. Maildroppa identifică toate endpoint-urile active abonate la acel eveniment.
3. Maildroppa creează câte o livrare pentru fiecare endpoint corespunzător.
4. Payload-ul JSON este semnat cu secretul de semnare pentru webhook-uri al contului.
5. Maildroppa trimite o solicitare HTTPS POST către URL-ul salvat al endpoint-ului.
6. Endpoint-ul verifică semnătura, stochează sau procesează evenimentul și returnează un răspuns HTTP.
7. Maildroppa înregistrează rezultatul în istoricul livrărilor și reîncearcă automat livrarea în cazul erorilor temporare.

Dacă mai multe endpoint-uri sunt abonate la același eveniment, fiecare primește propria livrare. Evenimentul de business are același ID pentru toate, în timp ce fiecare livrare are un ID propriu.

Webhook-urile la nivel de cont diferă de pasul „Send a webhook” dintr-o automatizare. Cele la nivel de cont urmăresc evenimentele selectate din întregul cont Maildroppa. Un webhook dintr-o automatizare este trimis numai când un abonat ajunge la pasul respectiv. Ambele folosesc secretul de semnare pentru webhook-uri al contului, astfel că rotirea secretului afectează toate sistemele receptoare care verifică semnăturile webhook-urilor trimise de Maildroppa.

Deschide pagina de webhook-uri

Deschide „Settings”, extinde „Developers” și selectează „Webhooks”.

Pagina conține trei zone principale:

• „Signing secret” — secretul de semnare
• „Endpoints” — endpoint-urile
• „Delivery history” — istoricul livrărilor pentru endpoint-ul selectat

Dacă ai mai multe endpoint-uri, selectează rândul unui endpoint pentru a-i afișa istoricul livrărilor. Dacă nu ai selectat explicit unul, Maildroppa afișează istoricul primului endpoint din listă.

Înainte de a crea un endpoint

Pregătește un sistem receptor pe server înainte de a configura Maildroppa. Acesta trebuie:

• Să fie disponibil la un URL HTTPS public.
• Să accepte solicitări POST cu un corp de tip application/json.
• Să păstreze corpul brut al solicitării până la verificarea semnăturii Maildroppa.
• Să returneze un cod de stare 2xx numai după acceptarea în siguranță a evenimentului.
• Să proceseze idempotent livrările repetate, folosind ID-ul evenimentului.
• Să răspundă rapid, fără să efectueze operațiuni lente în timpul solicitării.

O abordare fiabilă este să verifici solicitarea, să stochezi ID-ul evenimentului și payload-ul într-o coadă persistentă sau într-o bază de date, să returnezi 200 sau 204 și să procesezi ulterior acțiunea de business.

Nu expune un computer de dezvoltare, o adresă de rețea locală sau un script neprotejat ca sistem receptor de webhook-uri în producție. Maildroppa acceptă numai destinații HTTPS publice și verifică din nou destinația la trimiterea fiecărei livrări.

Pasul 1: Generează secretul de semnare

Fiecare solicitare webhook Maildroppa este semnată. Sistemul receptor folosește secretul de semnare pentru a verifica dacă solicitarea a fost creată de Maildroppa și dacă nu a fost modificat corpul acesteia în timpul transmiterii.

În partea de sus a paginii, panoul „Signing secret” afișează una dintre următoarele stări:

• Missing — Nu există încă un secret de semnare.
• Ready — Secretul de semnare este configurat.
• Loading — Maildroppa preia starea curentă.

Apasă „Generate secret” când starea este „Missing”.

Maildroppa afișează imediat noul secret. Acesta începe cu whsec_. Apasă „Copy” și stochează-l în managerul de secrete sau în configurația de mediu protejată pe care o folosește sistemul receptor.

Valoarea completă este afișată numai imediat după generare sau rotire. Când reîncarci pagina sau o părăsești, Maildroppa afișează doar faptul că există un secret și când a fost actualizat ultima dată. Secretul stocat nu este afișat din nou.

Dacă pierzi secretul

Dacă sistemul receptor nu mai are secretul curent, apasă „Rotate secret” și salvează noua valoare afișată.

Rotirea înlocuiește imediat secretul anterior. Maildroppa nu păstrează ambele valori pentru o perioadă de tranziție. Actualizează toate sistemele receptoare care folosesc acest secret al contului înainte de a trimite alte teste sau de a te baza pe livrările din producție.

Livrările noi, reîncercările programate, testele și retrimiterile sunt semnate cu secretul curent la momentul solicitării HTTP. Așadar, o livrare creată înainte de rotire poate fi semnată cu noul secret dacă încercarea de livrare are loc ulterior.

Tratează secretul ca pe o parolă

Nu include secretul de semnare în codul executat în browser, într-un depozit public de cod, într-un URL, într-o pagină de eroare sau într-un jurnal obișnuit al aplicației.

Doar sistemul receptor de pe server are nevoie de secret. Dacă bănuiești că acesta a fost expus, rotește-l și actualizează imediat toate sistemele receptoare.

Verifică semnătura unui webhook

Fiecare solicitare conține următoarele antete Maildroppa:

• X-Maildroppa-Event-Id — Identifică evenimentul de business.
• X-Maildroppa-Delivery-Id — Identifică livrarea respectivă.
• X-Maildroppa-Timestamp — Momentul semnării, exprimat în secunde Unix.
• X-Maildroppa-Signature — Semnătura HMAC cu versiune.

Maildroppa trimite și:

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

Semnătura are următorul format:

v1=<lowercase hexadecimal HMAC>

Maildroppa o generează folosind HMAC-SHA256. Conținutul semnat este alcătuit din marca temporală, urmată de un punct și de corpul brut exact al solicitării JSON:

<timestamp>.<raw request body>

Folosește secretul de semnare drept cheie HMAC.

Exemplul Node.js de mai jos ilustrează etapa esențială de verificare. rawBody trebuie să conțină octeții originali ai solicitării, nu un JSON deja parsat și serializat din nou.

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);
}

După verificarea semnăturii, compară și marca temporală cu ora serverului. Respinge solicitările din afara unui interval scurt de toleranță ales pentru infrastructura folosită, de exemplu cinci minute. Astfel reduci riscul ca o solicitare validă capturată să fie retrimisă mult mai târziu.

Parsează și procesează JSON-ul numai după ce ambele verificări au trecut.

Cauze frecvente ale erorilor de semnătură

Verificarea semnăturii eșuează de obicei din unul dintre următoarele motive:

• Sistemul receptor folosește un secret vechi după rotire.
• Middleware-ul a parsat sau a modificat JSON-ul înainte de calcularea semnăturii.
• Sistemul receptor semnează doar corpul solicitării și omite <timestamp>..
• Marca temporală este tratată ca o dată formatată, în loc să fie folosită valoarea exactă a antetului.
• Prefixul v1= este omis din comparație.
• HMAC-ul calculat folosește o altă codificare decât cea hexazecimală cu litere mici.

Înregistrează în jurnal ID-ul evenimentului și ID-ul livrării când verificarea eșuează, dar nu înregistra niciodată secretul de semnare sau valorile sensibile ale antetelor personalizate.

Pasul 2: Adaugă un endpoint

Apasă „Add endpoint” în secțiunea „Endpoints”.

Editorul conține patru părți:

• „Endpoint URL” — URL-ul endpoint-ului
• „Events” — evenimentele
• „Custom headers” — antetele personalizate
• Starea de activare, „Active”

Endpoint-urile noi sunt active, iar toate evenimentele afișate în editor sunt selectate inițial. Verifică selecția înainte de salvare, astfel încât sistemul receptor să primească doar notificările de care are nevoie.

Configurează URL-ul endpoint-ului

Introdu URL-ul public complet care trebuie să primească solicitările Maildroppa, de exemplu:

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

URL-ul trebuie să îndeplinească următoarele cerințe:

• Să folosească https://.
• Să conțină un nume de gazdă public valid.
• Să nu depășească 2.048 de caractere.
• Să nu conțină variabile de șablon cu { sau }.
• Să nu conțină un nume de utilizator sau o parolă înaintea numelui de gazdă.
• Să nu conțină un fragment URL care începe cu #.
• Să folosească portul HTTPS standard 443.
• Să nu folosească localhost, direct o adresă IP sau un nume de gazdă care se rezolvă la o adresă dintr-o rețea privată ori rezervată blocată.

Parametrii de interogare sunt acceptați, dar nu include chei API sau alte secrete în URL. URL-urile sunt vizibile în lista endpoint-urilor și în datele livrărilor. Folosește un antet personalizat pentru datele de autentificare.

Maildroppa nu urmează redirecționările. Salvează destinația HTTPS finală, nu un URL care returnează 301, 302, 307 sau 308.

Numele de gazdă al destinației este rezolvat din nou înainte de trimitere. Un nume de gazdă care ulterior se rezolvă la o adresă privată sau blocată este respins, chiar dacă era valid la salvarea endpoint-ului.

Alege evenimentele

Selectează cel puțin un eveniment. Un endpoint primește doar tipurile de evenimente selectate în editorul său.

Pagina oferă următoarele opțiuni de evenimente:

Subscriber Created — abonat creat — subscriber.created

Trimis când este creat un abonat în contul Maildroppa.

Folosește acest eveniment pentru a crea contactul corespunzător într-un CRM, într-o platformă de date despre clienți, într-o bază de date internă sau într-un alt sistem care ține cont de permisiuni.

Nu considera acest eveniment o dovadă că fiecare înscriere a trecut prin confirmarea prin e-mail a abonării (double opt-in). Starea abonatului din payload indică situația curentă.

Subscriber Updated — abonat actualizat — subscriber.updated

Trimis când se modifică informațiile standard despre abonat sau valorile câmpurilor personalizate.

Folosește obiectul complet al abonatului din payload ca reprezentare curentă a acestuia în Maildroppa. Nu presupune că s-a modificat o singură proprietate.

Atribuirea și eliminarea etichetelor au propriile tipuri de evenimente, astfel încât să poată fi gestionate separat.

Subscriber Unsubscribed — abonat dezabonat — subscriber.unsubscribed

Trimis când abonatul trece în starea dezabonat în urma unei acțiuni de dezabonare.

Folosește acest eveniment pentru a exclude contactul de la trimiteri în sistemele conectate. Nu reabona automat persoana doar pentru că un alt sistem marchează încă acel contact ca activ.

Tag Added — etichetă adăugată — subscriber.tag_added

Trimis când unui abonat i se atribuie o etichetă.

Payload-ul conține abonatul și eticheta implicată în modificarea respectivă.

Tag Removed — etichetă eliminată — subscriber.tag_removed

Trimis când o etichetă este eliminată de la un abonat.

Payload-ul conține abonatul actualizat și eticheta eliminată. Eticheta eliminată este furnizată separat, chiar dacă nu mai apare în array-ul curent tags al abonatului.

Form Submitted — formular trimis — form.submitted

Trimis când un vizitator trimite un formular de înscriere Maildroppa.

Tratează acest eveniment ca pe un semnal că formularul a fost trimis, nu ca pe o confirmare că procesul double opt-in a fost finalizat. Orice flux de lucru care necesită o abonare confirmată trebuie să țină în continuare cont de starea curentă a abonatului și de procesul de confirmare.

Folosește endpoint-uri separate pentru responsabilități diferite

Poți trimite evenimente diferite către sisteme diferite. De exemplu:

• Trimite evenimentele despre abonați și etichete către un CRM.
• Trimite evenimentele de dezabonare către un serviciu de excludere de la trimiteri.
• Trimite evenimentele de trimitere a formularelor către un flux de analiză a datelor.

Endpoint-urile separate reduc traficul inutil și simplifică diagnosticarea erorilor. Fiecare endpoint are propria selecție de evenimente, propriul URL, propriile antete personalizate, propria stare de activare, propriile teste și propriul istoric al livrărilor.

Adaugă antete personalizate

Antetele personalizate sunt opționale. Folosește-le când sistemul receptor necesită o cheie API, un token bearer, un identificator de tenant sau un alt antet fix.

Apasă „Add header”, apoi introdu numele în „Header name” și valoarea în „Header value”. Iată câteva exemple potrivite:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Poți adăuga cel mult 20 de antete personalizate.

Numele antetelor:

• Sunt obligatorii.
• Pot conține cel mult 128 de caractere.
• Trebuie să folosească doar caractere valide pentru numele antetelor HTTP.
• Trebuie să fie unice, fără a face diferența între litere mari și mici.

Valorile antetelor:

• Sunt obligatorii.
• Pot conține cel mult 2.000 de caractere.
• Nu pot conține caractere de linie nouă.

Următoarele nume sunt rezervate și nu pot fi înlocuite printr-un antet personalizat:

• Content-Type
• Content-Length
• Host
• User-Agent
• Orice nume care începe cu X-Maildroppa-

Astfel se împiedică înlocuirea antetelor de livrare și semnătură Maildroppa cu valori personalizate.

Cum sunt stocate secretele din antete

Maildroppa criptează valorile antetelor personalizate înainte de a le stoca. Valorile salvate nu sunt returnate browserului într-o formă lizibilă.

Când editezi ulterior endpoint-ul, câmpul valorii afișează „Stored value kept”, indicând că valoarea stocată este păstrată. Lasă câmpul gol dacă secretul existent trebuie să rămână neschimbat. Introdu o valoare nouă pentru a-l înlocui.

Dacă schimbi numele antetului, introdu din nou valoarea. Maildroppa păstrează un secret stocat numai atât timp cât numele original al antetului rămâne neschimbat.

Dacă elimini un rând de antet, acel antet nu va mai fi inclus în livrările viitoare după salvarea endpoint-ului.

Valorile antetelor personalizate sunt tratate ca informații sensibile în datele stocate despre solicitări. Acestea sunt mascate, nu afișate în istoricul livrărilor.

Setează endpoint-ul ca activ sau inactiv

Lasă opțiunea „Active” selectată când endpoint-ul este pregătit să primească imediat evenimente.

Debifeaz-o dacă vrei să salvezi configurația fără a începe livrările. Poți activa endpoint-ul ulterior din lista endpoint-urilor.

Un endpoint inactiv:

• Nu primește evenimente noi.
• Nu poate trimite un webhook de test.
• Rămâne vizibil și poate fi editat.
• Păstrează disponibil istoricul existent al livrărilor.

Activarea unui endpoint nu declanșează livrarea retroactivă a evenimentelor care au avut loc cât timp acesta a fost inactiv.

Apasă „Save” când URL-ul, selecția evenimentelor, antetele și starea sunt corecte.

Ce conține lista endpoint-urilor

Fiecare rând de endpoint afișează:

• URL-ul destinației.
• Un indicator „Active” sau „Inactive”.
• Tipurile de evenimente la care este abonat.
• Numărul de antete personalizate.
• Momentul ultimei actualizări a endpoint-ului.

Acțiunile disponibile sunt:

• On/Off — Activează sau dezactivează endpoint-ul.
• Test — Trimite imediat o singură solicitare de test către un endpoint activ.
• Edit — Modifică URL-ul, evenimentele, antetele sau starea de activare.
• Delete — Șterge definitiv configurația endpoint-ului după confirmare.

Selectează partea principală a unui rând pentru a deschide istoricul livrărilor acelui endpoint sub listă.

Cum afectează modificările salvate livrările existente

Un eveniment din cont creează o livrare care păstrează o copie a URL-ului endpoint-ului, a payload-ului și a antetelor personalizate din acel moment.

Editarea URL-ului sau a antetelor personalizate afectează livrările nou-create. O livrare deja pusă în coadă își păstrează destinația originală și configurația stocată a antetelor.

Modificarea evenimentelor selectate afectează, de asemenea, doar evenimentele care au loc ulterior. Maildroppa nu creează retroactiv livrări pentru tipuri de evenimente care nu erau selectate la momentul producerii evenimentului.

Secretul de semnare funcționează diferit: este citit la pregătirea solicitării HTTP. Prin urmare, o livrare în așteptare sau o retrimitere poate folosi un secret de semnare rotit recent, chiar dacă payload-ul și copia configurației endpoint-ului au fost create anterior.

Testează un endpoint

Apasă „Test” pe un endpoint activ după ce sistemul receptor și secretul de semnare sunt pregătite.

Maildroppa trimite imediat o singură solicitare semnată, folosind URL-ul și antetele personalizate salvate ale endpoint-ului. Modificările nesalvate dintr-un editor deschis nu sunt incluse în test.

Payload-ul de test folosește tipul de eveniment webhook.test și setează livemode la false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "Acesta este un webhook de test de la Maildroppa."
  }
}

ID-urile generate și marca temporală diferă la fiecare test efectiv.

Un test efectuează exact o încercare HTTP. Livrările de test nu sunt incluse în programul de reîncercări din producție și nu pot fi retrimise.

După încheierea solicitării, panoul de rezultate afișează:

• „Test success” sau „Test failed” — test reușit sau eșuat
• „Event ID” — ID-ul evenimentului
• „HTTP status” — codul de stare HTTP, dacă s-a primit un răspuns
• „Duration” — durata
• „Delivery ID” — ID-ul livrării
• Informații despre eroare, dacă sunt disponibile
• Un extras din răspuns, dacă sistemul receptor a returnat un corp de răspuns

Testul apare și în istoricul livrărilor, cu indicatorul „Test”. Folosește filtrul „Test” pentru a afișa numai solicitările de test.

Structura payload-ului din producție

Evenimentele din cont trimise în producție folosesc o structură JSON comună:

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

Proprietățile de la nivelul superior au următoarele semnificații:

• id — ID-ul evenimentului. Corespunde cu X-Maildroppa-Event-Id.
• type — Cheia evenimentului selectat în editorul endpoint-ului.
• schema_version — Versiunea schemei payload-ului. Folosește-o pentru a stabili cum parsezi evenimentul.
• created_at — Momentul creării payload-ului evenimentului, în UTC.
• livemode — true pentru evenimentele din producție și false pentru evenimentele de test.
• data — Conținutul specific evenimentului.

Direcționează evenimentele după valoarea exactă a proprietății type. Ignoră proprietățile suplimentare de care integrarea nu are nevoie, astfel încât extinderile compatibile ale payload-ului să nu afecteze funcționarea sistemului receptor.

Payload-ul evenimentelor despre abonați

Evenimentele despre abonați conțin reprezentarea curentă a abonatului în 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 și tags sunt array-uri și pot fi goale. O proprietate a abonatului poate avea și valoarea null când nu există o valoare definită. Sistemul receptor trebuie, așadar, să respecte schema payload-ului, fără să presupună că toate valorile opționale din profil sunt prezente.

Payload-ul evenimentelor despre etichete

Evenimentele despre etichete conțin atât abonatul, cât și eticheta care a declanșat evenimentul:

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

Pentru subscriber.tag_removed, data.tag identifică în continuare eticheta eliminată, chiar dacă array-ul curent tags al abonatului nu o mai conține.

ID-uri de eveniment, ID-uri de livrare și idempotență

ID-ul evenimentului și ID-ul livrării au scopuri diferite.

ID-ul evenimentului

ID-ul evenimentului identifică evenimentul de business. Apare în:

• Proprietatea id de la nivelul superior al payload-ului.
• Antetul X-Maildroppa-Event-Id al solicitării.
• Istoricul livrărilor.

Același eveniment poate fi trimis către mai multe endpoint-uri abonate. Livrările respective au același ID de eveniment.

Reîncercările și retrimiterile manuale păstrează, de asemenea, ID-ul original al evenimentului. Stochează ID-urile evenimentelor procesate și implementează acțiunea de business în mod idempotent, astfel încât o solicitare repetată să nu creeze contacte duplicate, să nu repete o acțiune ireversibilă și să nu aplice aceeași modificare de două ori.

ID-ul livrării

ID-ul livrării identifică o singură înregistrare de livrare. Apare în:

• Antetul X-Maildroppa-Delivery-Id al solicitării.
• Istoricul livrărilor.

Fiecare livrare către un endpoint are propriul ID. O retrimitere manuală creează un ID de livrare nou, păstrând ID-ul original al evenimentului.

Folosește ID-ul livrării pentru urmărire tehnică și asistență. Folosește ID-ul evenimentului pentru deduplicare la nivelul logicii de business.

Returnează răspunsul HTTP corect

Maildroppa clasifică răspunsurile astfel:

• Orice răspuns 2xx marchează livrarea ca reușită.
• Răspunsurile 408 Request Timeout, 429 Too Many Requests și 5xx indică erori temporare și permit reîncercarea livrării.
• Livrarea este reîncercată în cazul erorilor de rețea care pot fi temporare.
• Redirecționările și celelalte răspunsuri 3xx nu sunt urmate și sunt tratate ca eșecuri definitive.
• Celelalte răspunsuri 4xx sunt tratate ca eșecuri definitive, fără reîncercare.

Returnează 200, 202 sau 204 numai după acceptarea în siguranță a evenimentului. Dacă procesarea durează, stochează mai întâi evenimentul și returnează un răspuns de succes, apoi efectuează asincron operațiunea mai lentă.

Nu returna o redirecționare către un alt URL de webhook. Configurează direct URL-ul final în Maildroppa.

Programul de reîncercări automate

Livrările din producție pot avea până la șapte încercări HTTP.

După o eroare care permite reîncercarea, Maildroppa programează următoarea încercare la următoarele intervale:

1. După încercarea 1: 1 minut
2. După încercarea 2: 5 minute
3. După încercarea 3: 30 de minute
4. După încercarea 4: 2 ore
5. După încercarea 5: 12 ore
6. După încercarea 6: 24 de ore

Dacă și încercarea 7 se încheie cu o eroare care permite reîncercarea, livrarea trece în starea „Dead”, iar încercările automate se opresc.

Intervalele se calculează de la fiecare încercare eșuată. Livrarea efectivă poate avea loc puțin mai târziu, deoarece livrările sunt procesate asincron și sunt supuse și limitelor de protecție ale sistemului.

Ori de câte ori este posibil, remediază problema temporară a sistemului receptor înainte de momentul afișat la „Next retry”. Dacă încercările automate s-au încheiat, folosește „Replay” pentru a retrimite evenimentul după ce sistemul receptor funcționează din nou corect.

Cum citești istoricul livrărilor

Istoricul livrărilor aparține endpoint-ului selectat în acel moment. URL-ul endpoint-ului apare în antetul secțiunii, ca să poți verifica al cui istoric îl consulți.

Folosește următoarele filtre:

• All — Afișează livrările din producție și pe cele de test.
• Production — Afișează numai livrările de evenimente din producție.
• Test — Afișează numai testele manuale.

Apasă „Refresh” pentru a prelua cea mai recentă stare. Nu trebuie să lași istoricul deschis în timp ce Maildroppa trimite sau reîncearcă o livrare.

Pagina afișează cele mai recente 50 de livrări care corespund filtrului selectat.

Coloanele livrărilor

Fiecare rând conține:

• Created — Momentul creării înregistrării livrării.
• State — Starea: „Pending”, „Success”, „Failed” sau „Dead”.
• HTTP — Codul de stare al răspunsului, numărul de încercări, durata și, dacă este cazul, momentul următoarei reîncercări.
• Subscriber — Adresa de e-mail a abonatului, când evenimentul este asociat unui abonat.
• Delivery — Tipul evenimentului, ID-ul evenimentului și ID-ul livrării.
• Actions — Acțiunea „Replay”, dacă livrarea este eligibilă pentru retrimitere.

Dacă nu s-a efectuat nicio solicitare HTTP, coloana HTTP afișează „No HTTP attempt”. Acest lucru se poate întâmpla când Maildroppa respinge solicitarea înainte de trimitere, de exemplu deoarece lipsește secretul de semnare sau destinația salvată nu mai poate fi folosită în siguranță.

Când informațiile sunt disponibile, rândul afișează și eroarea, la „Error”, și un extras din răspunsul sistemului receptor, la „Response excerpt”. Nu include secrete sau date personale sensibile în corpul răspunsului la webhook, deoarece o parte din răspuns poate apărea în jurnalul livrărilor din cont.

Stările livrărilor

Pending înseamnă că livrarea este în așteptarea primei încercări sau a unei reîncercări programate. „Next retry” apare când a fost programată o nouă încercare.

Success înseamnă că sistemul receptor a returnat un răspuns 2xx. Nu mai este necesară nicio încercare automată.

Failed înseamnă că livrarea s-a încheiat din cauza unei probleme care nu permite reîncercarea, a fost respinsă înainte de o încercare HTTP sau a fost oprită înainte de trimitere.

Dead înseamnă că s-au epuizat toate încercările automate pentru o problemă care permitea reîncercarea, fără a primi un răspuns de succes.

Perioada de păstrare a istoricului

Înregistrările livrărilor sunt păstrate pentru o perioadă limitată:

• Livrări reușite din producție („Success”): 30 de zile
• Livrări eșuate din producție („Failed”): 90 de zile
• Livrări din producție cu încercările epuizate („Dead”): 90 de zile
• Livrări de test: 30 de zile

Păstrează propriile jurnale de integrare dacă ai nevoie de un istoric de audit mai îndelungat. Stochează ID-urile evenimentelor și ID-urile livrărilor, dar evită stocarea inutilă a secretelor.

Retrimite un eveniment

Apasă „Replay” când vrei să încerci din nou o livrare încheiată din producție.

Retrimiterea este disponibilă pentru livrările din producție aflate în starea „Success”, „Failed” sau „Dead”. Nu este disponibilă cât timp livrarea este în starea „Pending”, iar livrările de test nu pot fi retrimise.

O retrimitere:

• Creează o livrare nouă în starea „Pending”.
• Creează un ID de livrare nou.
• Păstrează ID-ul original al evenimentului.
• Păstrează tipul original al evenimentului și payload-ul JSON original.
• Folosește URL-ul destinației salvat inițial și copia originală a antetelor personalizate.
• Folosește secretul de semnare curent la pregătirea noii solicitări.

Retrimiterea nu reconstruiește payload-ul pe baza datelor curente ale abonatului, ci trimite din nou copia originală a evenimentului. Astfel, retrimiterea poate fi auditată, iar semnificația unui eveniment istoric nu se modifică în mod neobservat.

Pentru aceeași livrare sursă, o singură retrimitere poate fi în starea „Pending” la un moment dat. Așteaptă încheierea acesteia înainte de a solicita alta.

Asigură-te că endpoint-ul este în starea „Active” înainte de retrimitere. Dacă endpoint-ul este inactiv, retrimiterea pusă în coadă nu poate fi livrată cu succes.

Sistemul receptor poate să fi finalizat acțiunea de business chiar dacă Maildroppa nu a primit răspunsul de succes. De aceea, retrimiterea poate genera o solicitare duplicată. Deduplicarea după ID-ul evenimentului protejează sistemul conectat împotriva repetării acțiunii.

Editează un endpoint

Apasă „Edit” pentru a modifica URL-ul, selecția evenimentelor, antetele personalizate sau starea de activare.

Înainte de salvare:

1. Verifică dacă noul URL este deja disponibil.
2. Lasă goale câmpurile valorilor stocate ale antetelor dacă acestea trebuie să rămână neschimbate.
3. Introdu o valoare nouă pentru fiecare antet redenumit.
4. Verifică selecția evenimentelor pentru a nu elimina din greșeală notificări necesare.
5. Salvează și trimite un nou webhook de test.

Reține că livrările din coadă își păstrează URL-ul existent și copia existentă a antetelor personalizate. Testează noua configurație pentru livrările viitoare, fără să presupui că aceasta modifică o solicitare mai veche din coadă.

Dezactivează un endpoint

Folosește comutatorul „On/Off” pentru a suspenda o integrare fără să-i ștergi configurația și istoricul.

Când un endpoint este setat pe „Off”:

• Evenimentele noi nu mai sunt puse în coadă pentru acesta.
• Livrările în starea „Pending” care nu au fost deja preluate pentru trimitere sunt marcate „Failed”.
• Acțiunea „Test” este dezactivată.
• Endpoint-ul rămâne disponibil pentru editare și activare ulterioară.

O solicitare deja în curs în momentul dezactivării se poate finaliza în continuare. Verifică istoricul livrărilor după dezactivarea endpoint-ului dacă această distincție contează pentru integrare.

Evenimentele omise cât timp endpoint-ul este inactiv nu sunt livrate retroactiv când îl activezi din nou.

Șterge un endpoint

Apasă „Delete” și confirmă avertismentul când endpoint-ul nu mai trebuie păstrat.

Ștergerea elimină endpoint-ul de pe pagină, oprește livrările viitoare de evenimente și marchează ca eșuate livrările în așteptare care nu au fost deja preluate pentru trimitere.

Nu folosi ștergerea pentru a suspenda temporar o integrare. Folosește comutatorul „On/Off” dacă este posibil să mai ai nevoie de configurație sau de istoricul vizibil.

Înainte de ștergere, notează ID-urile evenimentelor și ale livrărilor de care mai ai nevoie pentru auditul integrării.

Depanare

Endpoint-ul nu poate fi salvat

Verifică următoarele:

• URL-ul începe cu https://.
• URL-ul folosește un nume de gazdă public și portul 443.
• URL-ul nu conține variabile, date de autentificare sau un fragment.
• Este selectat cel puțin un eveniment.
• Fiecare antet personalizat are un nume unic și o valoare.
• Numele rezervate pentru antetele Maildroppa și HTTP nu sunt folosite pentru antete personalizate.

Acțiunea „Test” este dezactivată

Testarea este disponibilă numai pentru un endpoint în starea „Active”. Setează endpoint-ul pe „On” sau editează-l și selectează „Active”, apoi salvează înainte de testare.

Testul afișează „No HTTP attempt”

Generează un secret de semnare dacă starea este „Missing”. Verifică și dacă numele de gazdă al destinației este public și se rezolvă în continuare corect.

O solicitare poate fi respinsă înainte de trimitere dacă secretul, URL-ul sau antetele personalizate sunt invalide ori dacă destinația nu trece verificarea de siguranță.

Sistemul receptor returnează 401 sau 403

Verifică numele salvat al antetului personalizat și datele de autentificare. Editează endpoint-ul și introdu din nou valoarea dacă aceasta s-a schimbat.

Verifică și dacă sistemul receptor nu confundă propriile date de autentificare API cu semnătura Maildroppa. Un antet de autorizare personalizat și X-Maildroppa-Signature au scopuri diferite și pot fi verificate independent.

Sistemul receptor returnează o redirecționare

Maildroppa nu urmează redirecționările. Înlocuiește URL-ul endpoint-ului cu URL-ul HTTPS public final și testează din nou.

Semnătura nu corespunde

Verifică dacă sistemul receptor:

• Folosește secretul de semnare curent.
• Folosește valoarea exactă din X-Maildroppa-Timestamp.
• Semnează <timestamp>.<raw request body>.
• Folosește HMAC-SHA256 și un rezultat hexazecimal cu litere mici.
• Compară valoarea completă, inclusiv v1=.
• Efectuează comparația înainte ca parsarea JSON să modifice corpul solicitării.

Același eveniment sosește de mai multe ori

Acest lucru se poate întâmpla după o întrerupere a rețelei, o reîncercare sau o retrimitere manuală. Este normal ca sistemele de livrare a webhook-urilor să folosească modelul de livrare „cel puțin o dată”, nu „exact o dată”.

Folosește ID-ul evenimentului drept cheie de idempotență. Returnează un răspuns 2xx când primești din nou ID-ul unui eveniment deja procesat și nu mai este necesară nicio acțiune.

O livrare este în starea „Pending”

Verifică „Next retry” în coloana HTTP. O eroare 408, 429 sau 5xx care permite reîncercarea ori o eroare temporară de rețea menține livrarea în starea „Pending” până la următoarea încercare programată.

Apasă „Refresh” după momentul reîncercării pentru a încărca cea mai recentă stare.

O livrare este în starea „Dead”

Toate încercările automate au fost epuizate. Remediază mai întâi problema sistemului receptor, asigură-te că endpoint-ul este în starea „Active”, trimite un webhook de test, apoi folosește „Replay” pentru livrarea din producție.

Listă de verificare recomandată pentru producție

Înainte de a te baza pe un endpoint în producție, verifică toate punctele de mai jos:

1. Sistemul receptor folosește un URL HTTPS public stabil, cu un certificat valid.
2. Secretul de semnare este stocat în afara codului sursă.
3. Semnătura este verificată pe baza corpului brut nemodificat al solicitării.
4. Mărcile temporale vechi sunt respinse conform unui interval de toleranță documentat.
5. Sistemul receptor stochează și deduplică ID-urile evenimentelor.
6. Sistemul receptor înregistrează în jurnal ID-urile evenimentelor și ale livrărilor pentru urmărire.
7. Procesarea lentă are loc după acceptarea evenimentului într-un mediu de stocare persistent.
8. Un răspuns 2xx este returnat numai pentru evenimentele acceptate.
9. Datele de autentificare personalizate sunt stocate în antete, nu în URL.
10. Sunt selectate numai tipurile de evenimente necesare.
11. Un webhook de test reușește și apare corect în istoricul livrărilor.
12. Sistemul de monitorizare te alertează când livrările din producție încep să returneze erori.

Cu aceste măsuri de protecție implementate, pagina „Webhooks” oferă ambele componente ale unei integrări fiabile: livrarea securizată a evenimentelor către aplicație și un istoric operațional clar în Maildroppa.