Configurează Webhook-uri

Published: 16 iulie 2026 · Last updated: 21 iulie 2026 · By Marcus Biel

Webhook-urile permit Maildroppa să notifice o altă aplicație atunci când se întâmplă ceva important în contul tău.

În loc să întrebi în mod repetat Maildroppa dacă un abonat a fost creat, actualizat, dezabonat sau căruia i s-a atribuit o etichetă, aplicația ta poate primi o solicitare HTTPS la scurt timp după producerea evenimentului.

Pagina Webhook-uri este locul central pentru această integrare la nivelul întregului cont. Poți crea mai multe endpoint-uri, poți alege evenimentele pe care le primește fiecare endpoint, poți adăuga antete de autentificare, testa conexiunea, inspecta încercările de livrare și relua un eveniment de producție atunci când este necesar.

Cum funcționează webhook-urile contului

Un webhook de cont urmează acest proces:

1. În Maildroppa are loc un eveniment, cum ar fi crearea unui abonat.
2. Maildroppa găsește fiecare endpoint activ abonat la evenimentul respectiv.
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 tău.
5. Maildroppa trimite o solicitare HTTPS POST către URL-ul endpoint-ului salvat.
6. Endpoint-ul tău 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 eșecurile temporare.

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

Webhook-urile contului diferă de pasul „Trimite un webhook” dintr-o automatizare. Webhook-urile contului ascultă evenimentele de cont selectate din Maildroppa. Un webhook de automatizare este trimis numai atunci când un abonat ajunge la acel pas. Ambele folosesc secretul de semnare pentru webhook-uri al contului, astfel încât rotirea secretului afectează fiecare receptor de webhook-uri trimise care verifică semnăturile Maildroppa.

Deschiderea paginii Webhook-uri

Deschide „Setări”, extinde „Dezvoltatori” și selectează „Webhook-uri”.

Pagina conține trei zone principale:

• Secret de semnare
• Endpoint-uri
• Istoricul livrărilor pentru endpoint-ul selectat

Când ai mai mult de un endpoint, selectează un rând de endpoint pentru a 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 receptor pe serverul tău înainte de a configura Maildroppa. Receptorul trebuie:

• Să fie disponibil printr-un URL HTTPS public.
• Să accepte solicitări POST cu un corp application/json.
• Să păstreze corpul brut al solicitării până când semnătura Maildroppa a fost verificată.
• Să returneze un cod de stare 2xx numai după ce evenimentul a fost acceptat în siguranță.
• Să proceseze livrările repetate idempotent, folosind ID-ul de eveniment.
• Să răspundă rapid, în loc să efectueze operațiuni lente în timpul solicitării.

Un model fiabil este să verifici solicitarea, să stochezi ID-ul evenimentului și payload-ul într-o coadă durabilă 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 receptor de webhook-uri pentru producție. Maildroppa acceptă numai destinații HTTPS publice și verifică din nou destinația atunci când trimite o livrare.

Pasul 1: Generează secretul de semnare

Fiecare solicitare webhook Maildroppa este semnată. Receptorul tău folosește secretul de semnare pentru a verifica dacă solicitarea a fost creată de Maildroppa și dacă organismul nu a fost modificat în tranzit.

În partea de sus a paginii, panoul Secret de semnare afișează una dintre aceste stări:

• Lipsește — Nu există încă niciun secret de semnare.
• Gata — Este configurat un secret de semnare.
• Se încarcă — Maildroppa preia starea curentă.

Apasă „Generează secret” când starea este Lipsă.

Maildroppa afișează imediat noul secret. Acesta începe cu whsec_. Apasă „Copiază” și stochează-l în managerul de secrete sau în configurația protejată a mediului utilizată de receptorul tău.

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ă receptorul nu mai are secretul curent, apasă „Rotește secretul” și salvează valoarea nou afișată.

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

Livrările noi, reîncercările programate, testele și reluările sunt semnate cu secretul curent în momentul solicitării HTTP. Aceasta înseamnă că o livrare creată înainte de rotire poate fi semnată tot cu noul secret atunci când este încercată ulterior.

Tratează secretul ca pe o parolă

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

Doar receptorul de pe server are nevoie de secret. Dacă bănuiești că a fost expus, rotește-l și actualizează imediat toți receptorii.

Verificarea semnăturii unui webhook

Fiecare solicitare conține aceste antete Maildroppa:

• X-Maildroppa-Event-Id — Identifică evenimentul de business.
• X-Maildroppa-Delivery-Id — Identifică această livrare anume.
• X-Maildroppa-Timestamp — Momentul semnării, exprimat în secunde Unix.
• X-Maildroppa-Signature — Semnătura HMAC versionată.

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 creează folosind HMAC-SHA256. Conținutul semnat este marca temporală, urmată de un punct, urmată de corpul brut exact al solicitării JSON:

<timestamp>.<raw request body>

Folosește secretul de semnare ca cheie HMAC.

Următorul exemplu Node.js arată pasul esențial de verificare. rawBody trebuie să fie octeții originali ai solicitării, nu JSON care a fost deja analizat ș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 tău. Respinge solicitările din afara unei toleranțe scurte alese pentru infrastructura ta, de exemplu cinci minute. Astfel reduci riscul ca o solicitare validă capturată să fie reluată mult mai târziu.

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

Cauze frecvente ale erorilor de semnătură

O semnătură eșuează de obicei din unul dintre aceste motive:

• Receptorul folosește un secret vechi după rotire.
• Middleware-ul a analizat sau modificat JSON-ul înainte de calcularea semnăturii.
• Receptorul semnează doar corpul ș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 este codificat diferit, în loc să fie reprezentat în hexazecimal cu litere mici.

Înregistrează 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ă „Adaugă endpoint” în secțiunea Endpoint-uri.

Editorul conține patru părți:

• URL endpoint
• Evenimente
• Antete personalizate
• Stare activă

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 receptorul să primească numai notificările de care are efectiv nevoie.

Configurarea URL-ului 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:

• Trebuie să folosească https://.
• Trebuie să conțină un nume de gazdă public valid.
• Poate avea cel mult 2.048 de caractere.
• Nu poate conține variabile de șablon cu { sau }.
• Nu poate conține un nume de utilizator sau o parolă înaintea numelui de gazdă.
• Nu poate conține un fragment URL care începe cu #.
• Trebuie să folosească portul HTTPS standard 443.
• Nu poate folosi localhost, o adresă IP brută sau un nume de gazdă care se rezolvă către o rețea privată sau rezervată blocată.

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

Maildroppa nu urmărește 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ă către o adresă privată sau blocată este respins chiar dacă era valid atunci când endpoint-ul a fost salvat.

Alegerea evenimentelor

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

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

Abonat creat — subscriber.created

Trimis atunci 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 interpreta acest eveniment ca dovadă că fiecare înscriere a finalizat Double Opt-in. Starea abonatului din payload descrie starea curentă.

Abonat actualizat — subscriber.updated

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

Folosește obiectul complet al abonatului din payload ca reprezentare curentă Maildroppa. Evită să presupui că s-a modificat o singură proprietate anume.

Atribuirile și eliminările de etichete au propriile tipuri de evenimente, astfel încât să poată fi gestionate separat.

Abonat dezabonat — subscriber.unsubscribed

Trimis atunci când abonatul trece în starea dezabonat printr-o acțiune de dezabonare.

Folosește acest eveniment pentru a suprima contactul în sistemele conectate. Nu reabona automat persoana deoarece un alt sistem marchează încă acel contact ca activ.

Etichetă adăugată — subscriber.tag_added

Trimis atunci când unei persoane abonate îi este atribuită o etichetă.

Payload-ul conține abonatul și eticheta implicată în această modificare anume.

Etichetă eliminată — subscriber.tag_removed

Trimis atunci 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 este prezentă în matricea curentă tags a abonatului.

Formular trimis — form.submitted

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

Tratează acest eveniment ca pe un semnal de trimitere a formularului, nu ca pe o confirmare că Double Opt-in a fost finalizat. Orice flux de lucru care necesită un abonament confirmat trebuie să respecte în continuare starea curentă a abonatului și procesul de confirmare.

Folosește endpoint-uri separate când responsabilitățile diferă

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 suprimare.
• Trimite evenimentele de trimitere a formularelor către un flux de analiză.

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

Adăugarea antetelor personalizate

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

Apasă „Adaugă antet”, apoi introdu Numele antetului și Valoarea antetului. Exemple potrivite includ:

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ă caractere valide pentru numele antetelor HTTP.
• Trebuie să fie unice, indiferent de folosirea literelor mari sau mici.

Valorile antetelor:

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

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 o valoare personalizată.

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ă „Valoarea stocată este păstrată”. Lasă-l gol când secretul existent trebuie să rămână neschimbat. Introdu o valoare nouă pentru a o înlocui.

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

Eliminarea unui rând de antet elimină acel antet din livrările viitoare după salvarea endpoint-ului.

Valorile antetelor personalizate sunt tratate ca sensibile în informațiile stocate despre solicitări. Ele sunt mascate și nu sunt afișate în istoricul livrărilor.

Setarea endpoint-ului ca activ sau inactiv

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

Debifeaz-o când 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 nou apărute.
• Nu poate trimite un webhook de test.
• Rămâne vizibil și editabil.
• Păstrează disponibil istoricul existent al livrărilor.

Activarea unui endpoint nu completează retroactiv evenimentele care au avut loc cât timp acesta a fost inactiv.

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

Înțelegerea listei de endpoint-uri

Fiecare rând de endpoint afișează:

• URL-ul destinației.
• O insignă Activ sau Inactiv.
• Tipurile de evenimente la care este abonat.
• Numărul de antete personalizate.
• Momentul ultimei actualizări a endpoint-ului.

Acțiunile disponibile sunt:

• Activat/Dezactivat — Activează sau dezactivează endpoint-ul.
• Testează — Trimite o solicitare de test imediată către un endpoint activ.
• Editează — Modifică URL-ul, evenimentele, antetele sau starea activă.
• Șterge — Elimină 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 de cont creează o livrare cu o captură 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 care se afla deja în coadă își păstrează destinația originală și configurația stocată a antetelor.

Modificarea evenimentelor selectate afectează, de asemenea, numai evenimentele care au loc ulterior. Maildroppa nu creează livrări retroactiv pentru tipurile de evenimente care nu erau selectate atunci când a avut loc evenimentul.

Secretul de semnare este diferit: este citit atunci când solicitarea HTTP este pregătită. Prin urmare, o livrare în așteptare sau o reluare poate folosi un secret de semnare rotit recent, chiar dacă payload-ul și captura endpoint-ului au fost create anterior.

Testarea unui endpoint

Apasă „Testează” pe un endpoint activ după ce receptorul și secretul de semnare sunt pregătite.

Maildroppa trimite imediat o solicitare semnată folosind URL-ul salvat al endpoint-ului și antetele personalizate salvate. Modificările nesalvate dintr-un editor deschis nu fac parte din 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ă pentru fiecare test real.

Un test face exact o încercare HTTP. Livrările de test nu sunt introduse în programul de reîncercări de producție și nu pot fi reluate.

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

• Test reușit sau Test eșuat
• ID eveniment
• Stare HTTP, atunci când a fost primit un răspuns
• Durată
• ID livrare
• Informații despre eroare, când sunt disponibile
• Un extras din răspuns, când receptorul a returnat un corp

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

Înțelegerea payload-ului de producție

Evenimentele de cont din producție folosesc un înveliș JSON comun:

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

Proprietățile de nivel superior înseamnă:

• 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 când decizi cum să analizezi evenimentul.
• created_at — Momentul creării payload-ului evenimentului, în UTC.
• livemode — true pentru evenimentele de producție și false pentru evenimentele de test.
• data — Conținutul specific evenimentului.

Direcționează evenimentele folosind valoarea exactă a lui type. Ignoră proprietățile suplimentare de care integrarea ta nu are nevoie, astfel încât adăugările compatibile ale payload-ului să nu întrerupă receptorul.

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 matrice. Ele pot fi goale. O proprietate a abonatului poate fi și null atunci când nu există nicio valoare, astfel încât receptorul tău trebuie să urmeze schema payload-ului, fără să presupună că fiecare valoare opțională de profil este prezentă.

Payload-ul evenimentelor despre etichete

Evenimentele despre etichete conțin atât abonatul, cât și eticheta care a cauzat 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ă matricea curentă tags a 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 de nivel superior id a payload-ului.
• Antetul solicitării X-Maildroppa-Event-Id.
• 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 reluările manuale păstrează, de asemenea, ID-ul original al evenimentului. Stochează ID-urile evenimentelor procesate și fă acțiunea de business idempotentă, astfel încât o solicitare repetată să nu creeze contacte duplicate, să nu repete o acțiune ireversibilă sau să nu aplice aceeași modificare de două ori.

ID-ul livrării

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

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

Fiecare livrare către un endpoint are propriul ID de livrare. O reluare manuală creează un nou ID de livrare, 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 nivel de business.

Returnarea răspunsului 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 sunt eșecuri temporare și pot fi reîncercate.
• Eșecurile de rețea care pot fi temporare sunt reîncercate.
• Redirecționările și alte răspunsuri 3xx nu sunt urmărite și sunt tratate ca eșecuri terminale.
• Celelalte răspunsuri 4xx sunt tratate ca eșecuri terminale și nu sunt reîncercate.

Returnează 200, 202 sau 204 numai când evenimentul a fost acceptat în siguranță. Dacă procesarea durează, stochează mai întâi evenimentul și returnează un răspuns de succes înainte de a efectua asincron operațiunea mai lentă.

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

Programul de reîncercare automată

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

După un eșec care permite reîncercarea, Maildroppa programează următoarea încercare cu aceste întârzieri:

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ă încercarea 7 primește în continuare un eșec care permite reîncercarea, livrarea devine Moartă și nu mai este programată nicio încercare automată.

Programul este măsurat de la fiecare încercare eșuată. Momentul efectiv al livrării poate fi puțin mai târziu deoarece livrările sunt procesate asincron și sunt supuse, de asemenea, limitelor de protecție ale sistemului.

Remediază problema temporară a receptorului înainte de momentul afișat pentru „Următoarea reîncercare”, ori de câte ori este posibil. Dacă încercările automate s-au încheiat, folosește Reluare după ce receptorul funcționează din nou.

Înțelegerea istoricului livrărilor

Istoricul livrărilor aparține endpoint-ului selectat în prezent. URL-ul endpoint-ului apare în antetul secțiunii, astfel încât să poți confirma ce istoric vizualizezi.

Folosește aceste filtre:

• Toate — Afișează livrările de producție și de test.
• Producție — Afișează numai livrările de evenimente live.
• Test — Afișează numai testele manuale.

Apasă „Reîmprospătează” pentru a prelua cea mai recentă stare. Nu este necesar 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 corespunzătoare filtrului selectat.

Coloanele livrărilor

Fiecare rând conține:

• Creat — Momentul creării înregistrării livrării.
• Stare — În așteptare, Reușită, Eșuată sau Moartă.
• HTTP — Starea răspunsului, numărul de încercări, durata și momentul următoarei reîncercări, când este cazul.
• Abonat — E-mailul abonatului atunci când evenimentul este asociat unui abonat.
• Livrare — Tipul evenimentului, ID-ul evenimentului și ID-ul livrării.
• Acțiuni — Reluare atunci când livrarea este eligibilă.

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

Când sunt disponibile, rândul afișează și o Eroare și un extras din răspunsul returnat de receptor. Nu returna secrete sau date personale sensibile în corpul răspunsului webhook, deoarece o parte a acestui răspuns poate apărea în jurnalul de livrări al contului.

Stările livrărilor

În așteptare înseamnă că livrarea așteaptă prima încercare sau o reîncercare programată. „Următoarea reîncercare” apare când a fost programată o altă încercare.

Reușită înseamnă că receptorul a returnat un răspuns 2xx. Nu mai este necesară nicio încercare automată.

Eșuată î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 a putea fi trimisă.

Moartă înseamnă că au fost utilizate toate încercările automate pentru o problemă care permitea reîncercarea, fără primirea unui răspuns de succes.

Păstrarea istoricului

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

• Livrări de producție reușite: 30 de zile
• Livrări de producție eșuate: 90 de zile
• Livrări de producție moarte: 90 de zile
• Livrări de test: 30 de zile

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

Reluarea unei livrări

Apasă „Reia” când o livrare de producție finalizată trebuie încercată din nou.

Reluarea este disponibilă pentru livrările de producție aflate în starea Reușită, Eșuată sau Moartă. Nu este disponibilă cât timp o livrare este În așteptare, iar livrările de test nu pot fi reluate.

O reluare:

• Creează o nouă livrare În așteptare.
• Creează un nou ID de livrare.
• Păstrează ID-ul original al evenimentului.
• Păstrează tipul original al evenimentului și payload-ul JSON original.
• Folosește URL-ul țintă original salvat și captura originală a antetelor personalizate.
• Folosește secretul de semnare curent atunci când este pregătită noua solicitare.

Reluarea nu reconstruiește payload-ul din datele curente ale abonatului. Retrimite captura originală a evenimentului. Astfel, reluarea poate fi urmărită și se împiedică schimbarea tăcută a semnificației unui eveniment istoric.

O singură reluare a aceleiași livrări sursă poate fi În așteptare la un moment dat. Așteaptă finalizarea acelei reluări înainte de a solicita alta.

Asigură-te că endpoint-ul este Activ înainte de reluare. Dacă endpoint-ul este inactiv, reluarea pusă în coadă nu poate fi livrată cu succes.

Deoarece un receptor poate fi finalizat acțiunea de business chiar dacă Maildroppa nu a primit răspunsul de succes, reluarea poate produce o solicitare duplicată. Deduplicarea după ID-ul evenimentului protejează sistemul conectat împotriva repetării acțiunii.

Editarea unui endpoint

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

Înainte de salvare:

1. Confirmă că noul URL este deja disponibil.
2. Lasă goale valorile stocate ale antetelor atunci când 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 accidental notificările necesare.
5. Salvează și trimite un nou webhook de test.

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

Dezactivarea unui endpoint

Folosește comutatorul Activat/Dezactivat când vrei să pui pe pauză o integrare fără a-i șterge configurația și istoricul.

Când un endpoint este dezactivat:

• Evenimentele noi nu mai sunt puse în coadă pentru acesta.
• Livrările În așteptare care nu au fost deja preluate pentru trimitere sunt marcate ca Eșuate.
• Testarea 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 este importantă pentru integrarea ta.

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

Ștergerea unui endpoint

Apasă „Șterge” și confirmă avertismentul când endpoint-ul nu mai trebuie să existe.

Ș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.

Ștergerea nu este o modalitate de a pune temporar pe pauză. Folosește comutatorul Activat/Dezactivat când este posibil să ai din nou nevoie de configurație sau de istoricul vizibil.

Înainte de ștergere, notează orice ID-uri de eveniment sau ID-uri de livrare de care mai ai nevoie pentru auditul integrării.

Depanare

Endpoint-ul nu poate fi salvat

Verifică dacă:

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

Testarea este dezactivată

Testarea este disponibilă numai pentru un endpoint Activ. Activează endpoint-ul sau editează-l și selectează „Activ”, apoi salvează înainte de testare.

Testul nu afișează nicio încercare HTTP

Generează un secret de semnare dacă starea este Lipsă. 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 atunci când secretul, URL-ul, antetele personalizate sau verificarea siguranței destinației sunt invalide.

Receptorul returnează 401 sau 403

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

Verifică și dacă receptorul nu confundă propria acreditare API cu semnătura Maildroppa. Un antet de autorizare personalizat și X-Maildroppa-Signature au scopuri diferite și pot fi verificate independent.

Receptorul returnează o redirecționare

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

Semnătura nu corespunde

Confirmă că receptorul:

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

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 reluare manuală. Este normal ca sistemele de livrare a webhook-urilor să ofere livrare cel puțin o dată, nu livrare exact o dată.

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

O livrare este în așteptare

Verifică „Următoarea reîncercare” în coloana HTTP. O eroare temporară 408, 429, 5xx sau o eroare temporară de rețea rămâne În așteptare până la următoarea încercare programată.

Apasă „Reîmprospătează” după momentul reîncercării pentru a încărca starea cea mai recentă.

O livrare este moartă

Au fost utilizate toate încercările automate. Repară mai întâi receptorul, asigură-te că endpoint-ul este Activ, trimite un webhook de test și apoi folosește Reluare pentru livrarea de producție.

Listă de verificare recomandată pentru producție

Înainte de a te baza pe un endpoint în producție, confirmă toate următoarele:

1. Receptorul 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ă folosind corpul brut nemodificat.
4. Mărcile temporale vechi sunt respinse conform unei toleranțe documentate.
5. Receptorul stochează și deduplicatează ID-urile evenimentelor.
6. Receptorul înregistrează ID-urile evenimentelor și ID-urile livrărilor pentru urmărire.
7. Procesarea lentă are loc după acceptarea durabilă a evenimentului.
8. Un răspuns 2xx este returnat numai pentru evenimentele acceptate.
9. Acreditările 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. Monitorizarea te alertează când livrările de producție încep să returneze erori.

Cu aceste măsuri de protecție implementate, pagina Webhook-uri oferă ambele părți ale unei integrări fiabile: livrarea securizată a evenimentelor către aplicația ta și un istoric operațional clar în Maildroppa.