Konfigurer webhooks

Published: 16. juli 2026 · Last updated: 21. juli 2026 · By Marcus Biel

Webhooks giver Maildroppa mulighed for at underrette en anden applikation, når der sker noget vigtigt på din konto.

I stedet for gentagne gange at spørge Maildroppa, om en abonnent er blevet oprettet, opdateret, afmeldt eller har fået tildelt et tag, kan din applikation modtage en HTTPS-anmodning kort efter, at hændelsen finder sted.

Siden Webhooks er det centrale sted for denne kontodækkende integration. Du kan oprette flere endpoints, vælge hvilke hændelser hvert endpoint modtager, tilføje godkendelsesheadere, teste forbindelsen, se leveringsforsøg og afspille en produktionhændelse igen, når det er nødvendigt.

Sådan fungerer konto-webhooks

Et konto-webhook følger denne proces:

1. Der sker en hændelse i Maildroppa, f.eks. at en abonnent oprettes.
2. Maildroppa finder alle aktive endpoints, der abonnerer på denne hændelse.
3. Maildroppa opretter én levering for hvert matchende endpoint.
4. JSON-nyttelasten signeres med din kontos webhook Signing secret.
5. Maildroppa sender en HTTPS POST-anmodning til den gemte endpoint-URL.
6. Dit endpoint verificerer signaturen, gemmer eller behandler hændelsen og returnerer et HTTP-svar.
7. Maildroppa registrerer resultatet i leveringshistorikken og forsøger automatisk igen ved midlertidige fejl.

Hvis flere endpoints abonnerer på den samme hændelse, modtager hvert endpoint sin egen levering. Forretningshændelsen har samme Event ID for dem alle, mens hver levering har sit eget Delivery ID.

Konto-webhooks adskiller sig fra et trin med navnet “Send a webhook” i en Automation. Konto-webhooks lytter efter udvalgte kontohændelser på tværs af Maildroppa. Et Automation-webhook sendes kun, når en abonnent når frem til netop dette trin. Begge bruger kontoens webhook Signing secret, så rotation af hemmeligheden påvirker alle udgående webhook-modtagere, der verificerer Maildroppa-signaturer.

Åbning af siden Webhooks

Åbn “Settings”, udvid “Developers”, og vælg “Webhooks”.

Siden indeholder tre hovedområder:

• Signing secret
• Endpoints
• Leveringshistorik for det valgte endpoint

Når du har mere end ét endpoint, skal du vælge en endpoint-række for at få vist leveringshistorikken. Hvis du ikke har valgt et endpoint specifikt, viser Maildroppa historikken for det første endpoint på listen.

Før du opretter et endpoint

Gør en modtager klar på din server, før du konfigurerer Maildroppa. Modtageren bør:

• Være tilgængelig via en offentlig HTTPS-URL.
• Acceptere POST-anmodninger med en application/json-body.
• Bevare den rå request-body, indtil Maildroppa-signaturen er verificeret.
• Returnere en 2xx-status, først når hændelsen er accepteret sikkert.
• Behandle gentagne leveringer idempotent ved at bruge Event ID.
• Svare hurtigt i stedet for at udføre langsomt arbejde under anmodningen.

Et pålideligt mønster er at verificere anmodningen, gemme Event ID og nyttelasten i en permanent kø eller database, returnere 200 eller 204 og derefter behandle forretningshandlingen.

Eksponér ikke en udviklingscomputer, en lokal netværksadresse eller et ubeskyttet script som produktionsmodtager for webhooks. Maildroppa accepterer kun offentlige HTTPS-mål og kontrollerer destinationen igen, når en levering sendes.

Trin 1: Generer Signing secret

Alle Maildroppa-webhookanmodninger er signerede. Din modtager bruger Signing secret til at verificere, at anmodningen er oprettet af Maildroppa, og at body-indholdet ikke er blevet ændret under transporten.

Øverst på siden viser panelet Signing secret en af disse tilstande:

• Missing — Der findes endnu ingen Signing secret.
• Ready — En Signing secret er konfigureret.
• Loading — Maildroppa henter den aktuelle status.

Klik på “Generate secret”, når status er Missing.

Maildroppa viser den nye hemmelighed med det samme. Den begynder med whsec_. Klik på “Copy”, og gem den i den secret manager eller beskyttede miljøkonfiguration, som din modtager bruger.

Hele værdien vises kun umiddelbart efter generering eller rotation. Når du genindlæser eller forlader siden, viser Maildroppa kun, at der findes en hemmelighed, og hvornår den sidst blev opdateret. Den gemte hemmelighed vises ikke igen.

Hvis du mister hemmeligheden

Hvis modtageren ikke længere har den aktuelle hemmelighed, skal du klikke på “Rotate secret” og gemme den nyligt viste værdi.

Rotation erstatter den tidligere hemmelighed med det samme. Maildroppa gemmer ikke begge værdier i en overgangsperiode. Opdatér alle modtagere, der bruger denne kontohæmmlighed, før du sender flere tests eller stoler på produktionsleveringer.

Nye leveringer, planlagte forsøg, tests og afspilninger signeres med den aktuelle hemmelighed på tidspunktet for HTTP-anmodningen. Det betyder, at en levering, der blev oprettet før rotation, stadig kan blive signeret med den nye hemmelighed, når den forsøges sendt efter rotationen.

Behandl hemmeligheden som en adgangskode

Placér ikke Signing secret i browserkode, et offentligt repository, en URL, en fejlside eller en almindelig applikationslog.

Det er kun servermodtageren, der har brug for hemmeligheden. Hvis du tror, at den er blevet eksponeret, skal du straks rotere den og opdatere alle modtagere.

Verificering af en webhook-signatur

Hver anmodning indeholder disse Maildroppa-headere:

• X-Maildroppa-Event-Id — Identificerer forretningshændelsen.
• X-Maildroppa-Delivery-Id — Identificerer denne bestemte levering.
• X-Maildroppa-Timestamp — Signeringstidspunktet som Unix-sekunder.
• X-Maildroppa-Signature — Den versionsbestemte HMAC-signatur.

Maildroppa sender også:

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

Signaturen har dette format:

v1=<lowercase hexadecimal HMAC>

Maildroppa opretter den med HMAC-SHA256. Det signerede indhold er timestampet efterfulgt af et punktum og den nøjagtige rå JSON-request-body:

<timestamp>.<raw request body>

Brug Signing secret som HMAC-nøgle.

Følgende Node.js-eksempel viser det væsentlige verificeringstrin. rawBody skal være de oprindelige request-bytes, ikke JSON, der allerede er blevet parsed og serialiseret igen.

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

Efter verificering af signaturen skal du også sammenligne timestampet med din servertid. Afvis anmodninger uden for en kort tolerance, der er valgt til din infrastruktur, f.eks. fem minutter. Det reducerer risikoen for, at en opsnappet gyldig anmodning afspilles meget senere.

Parс kun JSON-indholdet, og behandl det først, når begge kontroller er bestået.

Almindelige årsager til signaturfejl

En signatur mislykkes normalt af en af disse årsager:

• Modtageren bruger en gammel hemmelighed efter rotation.
• Middleware parsed eller ændrede JSON-indholdet, før signaturen blev beregnet.
• Modtageren signerer kun body-indholdet og udelader <timestamp>..
• Timestampet behandles som en formatteret dato i stedet for den nøjagtige headerværdi.
• Præfikset v1= udelades i sammenligningen.
• Den beregnede HMAC kodes anderledes end som små bogstaver i hexadecimal form.

Log Event ID og Delivery ID, når verificeringen mislykkes, men log aldrig Signing secret eller følsomme værdier i brugerdefinerede headere.

Trin 2: Tilføj et endpoint

Klik på “Add endpoint” i sektionen Endpoints.

Editoren indeholder fire dele:

• Endpoint URL
• Events
• Custom headers
• Active status

Nye endpoints starter som Active, og alle hændelser, der vises i editoren, er valgt fra begyndelsen. Gennemgå valget, før du gemmer, så modtageren kun får de underretninger, den faktisk har brug for.

Konfiguration af endpoint-URL’en

Indtast den komplette offentlige URL, der skal modtage Maildroppa-anmodninger, f.eks.:

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

URL’en skal opfylde disse krav:

• Den skal bruge https://.
• Den skal indeholde et gyldigt offentligt hostname.
• Den kan være op til 2.048 tegn lang.
• Den må ikke indeholde template-variabler med { eller }.
• Den må ikke indeholde et brugernavn eller en adgangskode før hostname.
• Den må ikke indeholde et URL-fragment, der begynder med #.
• Den skal bruge standard-HTTPS-porten 443.
• Den må ikke bruge localhost, en rå IP-adresse eller et hostname, der peger på et blokeret privat eller reserveret netværk.

Forespørgselsparametre understøttes, men placér ikke API-nøgler eller andre hemmeligheder i URL’en. URL’er er synlige på endpoint-listen og i leveringsdata. Brug i stedet en Custom header til legitimationsoplysninger.

Maildroppa følger ikke redirects. Gem den endelige HTTPS-destination i stedet for en URL, der returnerer 301, 302, 307 eller 308.

Destinationens hostname slås op igen, før anmodningen sendes. Et hostname, der senere peger på en privat eller blokeret adresse, afvises, selv om det var gyldigt, da endpointet blev gemt.

Valg af hændelser

Vælg mindst én hændelse. Et endpoint modtager kun de hændelsestyper, der er valgt i dets editor.

Siden tilbyder disse hændelsesvalg:

Subscriber Created — subscriber.created

Sendes, når en abonnent oprettes på Maildroppa-kontoen.

Brug denne hændelse til at oprette den tilsvarende kontakt i et CRM-system, en kundedataplatform, en intern database eller et andet system, der tager højde for tilladelser.

Fortolk ikke denne hændelse som et bevis på, at enhver tilmelding har gennemført Double Opt-in. Abonnentstatussen i nyttelasten beskriver den aktuelle tilstand.

Subscriber Updated — subscriber.updated

Sendes, når indbyggede abonnentoplysninger eller værdier i brugerdefinerede felter ændres.

Brug det komplette abonnentobjekt i nyttelasten som den aktuelle Maildroppa-repræsentation. Antag ikke, at kun én bestemt egenskab er ændret.

Tildeling og fjernelse af tags har deres egne hændelsestyper, så de kan håndteres separat.

Subscriber Unsubscribed — subscriber.unsubscribed

Sendes, når abonnenten går over i status som afmeldt via en afmeldingshandling.

Brug denne hændelse til at undertrykke kontakten i forbundne systemer. Tilmeld ikke personen automatisk igen, fordi et andet system stadig markerer kontakten som aktiv.

Tag Added — subscriber.tag_added

Sendes, når et tag tildeles en abonnent.

Nyttelasten indeholder abonnenten og det tag, der indgår i netop denne ændring.

Tag Removed — subscriber.tag_removed

Sendes, når et tag fjernes fra en abonnent.

Nyttelasten indeholder den opdaterede abonnent og det fjernede tag. Det fjernede tag angives separat, selv om det ikke længere findes i abonnentens aktuelle tags-array.

Form Submitted — form.submitted

Sendes, når en besøgende indsender en Maildroppa-tilmeldingsformular.

Betragt dette som et signal om formularindsendelse, ikke som en bekræftelse på, at Double Opt-in er gennemført. Alle workflows, der kræver et bekræftet abonnement, skal fortsat respektere abonnentens aktuelle status og bekræftelsesprocessen.

Brug separate endpoints, når ansvaret er forskelligt

Du kan sende forskellige hændelser til forskellige systemer. For eksempel:

• Send abonnent- og taghændelser til et CRM-system.
• Send afmeldingshændelser til en undertrykkelsestjeneste.
• Send formularindsendelser til en analysepipeline.

Separate endpoints reducerer unødvendig trafik og gør fejl lettere at diagnosticere. Hvert endpoint har sit eget hændelsesvalg, sin egen URL, sine egne brugerdefinerede headere, aktive status, tests og leveringshistorik.

Tilføjelse af brugerdefinerede headere

Brugerdefinerede headere er valgfrie. Brug dem, når modtageren kræver en API-nøgle, et bearer-token, en tenant-identifikator eller en anden fast header.

Klik på “Add header”, og indtast Header name og Header value. Egnede eksempler omfatter:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Du kan tilføje op til 20 brugerdefinerede headere.

Headernavne:

• Er påkrævede.
• Kan indeholde op til 128 tegn.
• Skal bruge gyldige tegn til HTTP-headernavne.
• Skal være unikke uden hensyn til store og små bogstaver.

Headerværdier:

• Er påkrævede.
• Kan indeholde op til 2.000 tegn.
• Må ikke indeholde linjeskift.

Følgende navne er reserverede og kan ikke erstattes af en brugerdefineret header:

• Content-Type
• Content-Length
• Host
• User-Agent
• Alle navne, der begynder med X-Maildroppa-

Det forhindrer, at en brugerdefineret værdi erstatter Maildroppas leverings- og signaturheadere.

Sådan gemmes headerhemmeligheder

Maildroppa krypterer brugerdefinerede headerværdier, før de gemmes. Gemte værdier returneres ikke til browseren i læsbar form.

Når du senere redigerer endpointet, viser værdifeltet “Stored value kept”. Lad feltet være tomt, når den eksisterende hemmelighed skal forblive uændret. Indtast en ny værdi for at erstatte den.

Hvis du ændrer headernavnet, skal du indtaste værdien igen. Maildroppa bevarer kun en gemt hemmelighed, så længe det oprindelige headernavn forbliver uændret.

Hvis du fjerner en header-række, fjernes den pågældende header fra fremtidige leveringer, når endpointet er gemt.

Brugerdefinerede headerværdier behandles som følsomme i gemte requestoplysninger. De maskeres i stedet for at blive vist i leveringshistorikken.

Indstil endpointet til Active eller Inactive

Lad “Active” være valgt, når endpointet er klar til at modtage hændelser med det samme.

Fjern markeringen, når du vil gemme konfigurationen uden at starte leveringer. Du kan aktivere endpointet senere fra endpoint-listen.

Et inaktivt endpoint:

• Modtager ikke nye hændelser.
• Kan ikke sende en Test webhook.
• Forbliver synligt og redigerbart.
• Bevarer sin eksisterende leveringshistorik.

Aktivering af et endpoint udfylder ikke hændelser, der fandt sted, mens det var inaktivt.

Klik på “Save”, når URL, hændelsesvalg, headere og status er korrekte.

Forstå endpoint-listen

Hver endpoint-række viser:

• Destinations-URL’en.
• Et Active- eller Inactive-badge.
• De hændelsestyper, der abonneres på.
• Antallet af brugerdefinerede headere.
• Tidspunktet, hvor endpointet sidst blev opdateret.

De tilgængelige handlinger er:

• On/Off — Aktiverer eller deaktiverer endpointet.
• Test — Sender én øjeblikkelig testanmodning til et aktivt endpoint.
• Edit — Ændrer URL, hændelser, headere eller aktiv status.
• Delete — Fjerner endpointkonfigurationen permanent efter bekræftelse.

Vælg hoveddelen af en række for at åbne det pågældende endpoints leveringshistorik under listen.

Sådan påvirker gemte ændringer eksisterende leveringer

En kontohændelse opretter en levering med et øjebliksbillede af endpoint-URL, nyttelast og brugerdefinerede headere på det pågældende tidspunkt.

Redigering af URL eller brugerdefinerede headere påvirker nye leveringer. En levering, der allerede er sat i kø, beholder sin oprindelige destination og gemte headerkonfiguration.

Ændring af de valgte hændelser påvirker også kun hændelser, der finder sted efterfølgende. Maildroppa opretter ikke leveringer retroaktivt for hændelsestyper, der ikke var valgt, da hændelsen fandt sted.

Signing secret er anderledes: Den læses, når HTTP-anmodningen klargøres. En ventende levering eller afspilning kan derfor bruge en nyligt roteret Signing secret, selv om dens nyttelast og endpoint-øjebliksbillede blev oprettet tidligere.

Test af et endpoint

Klik på “Test” på et aktivt endpoint, når modtageren og Signing secret er klar.

Maildroppa sender straks én signeret anmodning ved hjælp af den gemte endpoint-URL og de gemte brugerdefinerede headere. Ikke-gemte ændringer i en åben editor indgår ikke i testen.

Testnyttelasten bruger hændelsestypen webhook.test og sætter livemode til 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."
  }
}

De genererede ID’er og timestampet er forskellige for hver rigtig test.

En test foretager præcis ét HTTP-forsøg. Testleveringer sættes ikke på den produktionsmæssige retry-plan og kan ikke afspilles.

Når anmodningen er afsluttet, viser resultatpanelet:

• Test success eller Test failed
• Event ID
• HTTP-status, når der blev modtaget et svar
• Varighed
• Delivery ID
• Fejloplysninger, når de er tilgængelige
• Et uddrag af svaret, når modtageren returnerede en body

Testen vises også i leveringshistorikken med et Test-badge. Brug filteret “Test” for kun at vise testanmodninger.

Forstå produktionsnyttelasten

Produktionens kontohændelser bruger en fælles JSON-envelope:

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

Egenskaberne på øverste niveau betyder:

• id — Event ID. Det matcher X-Maildroppa-Event-Id.
• type — Den hændelsesnøgle, der er valgt i endpoint-editoren.
• schema_version — Versionen af nyttelastens schema. Brug den, når du beslutter, hvordan hændelsen skal parses.
• created_at — Tidspunktet, hvor hændelsesnyttelasten blev oprettet, i UTC.
• livemode — true for produktionshændelser og false for testhændelser.
• data — Det hændelsesspecifikke indhold.

Dirigér hændelser efter den nøjagtige type-værdi. Ignorér ekstra egenskaber, som din integration ikke har brug for, så kompatible udvidelser af nyttelasten ikke ødelægger modtageren.

Nyttelast for abonnenthændelser

Abonnenthændelser indeholder den aktuelle abonnentrepræsentation i 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 og tags er arrays. De kan være tomme. En abonnentegenskab kan også være null, når der ikke findes nogen værdi, så din modtager bør følge nyttelastens schema i stedet for at antage, at alle valgfrie profilværdier er til stede.

Nyttelast for taghændelser

Taghændelser indeholder både abonnenten og det tag, der udløste hændelsen:

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

For subscriber.tag_removed identificerer data.tag stadig det fjernede tag, selv om abonnentens aktuelle tags-array ikke længere indeholder det.

Event ID, Delivery ID og idempotens

Event ID og Delivery ID tjener forskellige formål.

Event ID

Event ID identificerer forretningshændelsen. Det vises i:

• Nyttelastens id-egenskab på øverste niveau.
• Request-headeren X-Maildroppa-Event-Id.
• Leveringshistorikken.

Den samme hændelse kan sendes til flere abonnerede endpoints. Disse leveringer deler Event ID.

Retries og manuelle afspilninger beholder også det oprindelige Event ID. Gem behandlede Event ID’er, og gør forretningshandlingen idempotent, så en gentagen anmodning ikke opretter dublerede kontakter, gentager en irreversibel handling eller anvender den samme ændring to gange.

Delivery ID

Delivery ID identificerer én leveringspost. Det vises i:

• Request-headeren X-Maildroppa-Delivery-Id.
• Leveringshistorikken.

Hver endpoint-levering har sit eget Delivery ID. En manuel afspilning opretter et nyt Delivery ID, mens det oprindelige Event ID bevares.

Brug Delivery ID til teknisk sporing og support. Brug Event ID til deduplikering på forretningsniveau.

Returnering af det korrekte HTTP-svar

Maildroppa klassificerer svar således:

• Alle 2xx-svar markerer leveringen som vellykket.
• 408 Request Timeout, 429 Too Many Requests og 5xx-svar er midlertidige fejl og kan forsøges igen.
• Netværksfejl, der kan være midlertidige, forsøges igen.
• Redirects og andre 3xx-svar følges ikke og behandles som permanente fejl.
• Andre 4xx-svar behandles som permanente fejl og forsøges ikke igen.

Returnér kun 200, 202 eller 204, når hændelsen er accepteret sikkert. Hvis behandlingen tager tid, skal du først gemme hændelsen og returnere et succes-svar, før det langsommere arbejde udføres asynkront.

Returnér ikke en redirect til en anden webhook-URL. Konfigurér i stedet den endelige URL i Maildroppa.

Automatisk retry-plan

Produktionsleveringer kan foretage op til syv HTTP-forsøg.

Efter en fejl, der kan forsøges igen, planlægger Maildroppa det næste forsøg med disse forsinkelser:

1. Efter forsøg 1: 1 minut
2. Efter forsøg 2: 5 minutter
3. Efter forsøg 3: 30 minutter
4. Efter forsøg 4: 2 timer
5. Efter forsøg 5: 12 timer
6. Efter forsøg 6: 24 timer

Hvis forsøg 7 stadig modtager en fejl, der kan forsøges igen, bliver leveringen Dead, og der planlægges ikke flere automatiske forsøg.

Planen måles fra de enkelte mislykkede forsøg. Det faktiske leveringstidspunkt kan være lidt senere, fordi leveringer behandles asynkront og også er underlagt systemets beskyttelsesbegrænsninger.

Afhjælp om muligt et midlertidigt problem hos modtageren, før det viste tidspunkt for “Next retry” nås. Hvis de automatiske forsøg er afsluttet, skal du bruge Replay, når modtageren er sund igen.

Forstå leveringshistorikken

Leveringshistorikken tilhører det aktuelt valgte endpoint. Endpoint-URL’en vises i sektionens overskrift, så du kan bekræfte, hvilken historik du ser.

Brug disse filtre:

• All — Viser produktions- og testleveringer.
• Production — Viser kun live-hændelsesleveringer.
• Test — Viser kun manuelle tests.

Klik på “Refresh” for at hente den nyeste status. Historikken behøver ikke være åben, mens Maildroppa sender eller forsøger at sende en levering igen.

Siden viser de seneste 50 matchende leveringer for det valgte filter.

Leveringskolonner

Hver række indeholder:

• Created — Hvornår leveringsposten blev oprettet.
• State — Pending, Success, Failed eller Dead.
• HTTP — Svarstatus, antal forsøg og varighed samt tidspunktet for næste forsøg, når det er relevant.
• Subscriber — Abonnentens e-mail, når hændelsen er knyttet til en abonnent.
• Delivery — Hændelsestype, Event ID og Delivery ID.
• Actions — Replay, når leveringen er kvalificeret.

Hvis der ikke blev foretaget en HTTP-anmodning, viser HTTP-kolonnen “No HTTP attempt”. Det kan ske, når Maildroppa afviser anmodningen, før den sendes, f.eks. fordi Signing secret mangler, eller den gemte destination ikke længere kan bruges sikkert.

Når det er tilgængeligt, viser rækken også en Error og et Response excerpt, som modtageren har returneret. Returnér ikke hemmeligheder eller følsomme personoplysninger i et webhook-svar, fordi en del af svaret kan vises i kontoens leveringslog.

Leveringstilstande

Pending betyder, at leveringen venter på sit første forsøg eller et planlagt retry. “Next retry” vises, når endnu et forsøg er planlagt.

Success betyder, at modtageren returnerede et 2xx-svar. Der kræves ikke flere automatiske forsøg.

Failed betyder, at leveringen sluttede med et problem, der ikke kan forsøges igen, blev afvist før et HTTP-forsøg eller blev stoppet, før den kunne sendes.

Dead betyder, at alle automatiske forsøg på grund af et problem, der kunne forsøges igen, blev brugt uden at modtage et succesfuldt svar.

Opbevaring af historik

Leveringsposter opbevares i en begrænset periode:

• Vellykkede produktionsleveringer: 30 dage
• Mislykkede produktionsleveringer: 90 dage
• Dead-produktionsleveringer: 90 dage
• Testleveringer: 30 dage

Før dine egne integrationslogs, når du har brug for en længere revisionshistorik. Gem Event ID’er og Delivery ID’er, men undgå at gemme hemmeligheder unødvendigt.

Afspilning af en levering

Klik på “Replay”, når en afsluttet produktionslevering skal forsøges sendt igen.

Replay er tilgængelig for produktionsleveringer i tilstanden Success, Failed eller Dead. Den er ikke tilgængelig, mens en levering er Pending, og testleveringer kan ikke afspilles.

En afspilning:

• Opretter en ny Pending-levering.
• Opretter et nyt Delivery ID.
• Bevarer det oprindelige Event ID.
• Bevarer den oprindelige hændelsestype og JSON-nyttelast.
• Bruger det oprindeligt gemte mål-URL og øjebliksbilledet af brugerdefinerede headere.
• Bruger den aktuelle Signing secret, når den nye anmodning klargøres.

Replay genopbygger ikke nyttelasten ud fra abonnentens aktuelle data. Den sender det oprindelige hændelsesøjebliksbillede igen. Det gør afspilningen revisionssporbar og forhindrer, at en historisk hændelse ændrer betydning ubemærket.

Kun én afspilning af den samme kild levering kan være Pending ad gangen. Vent, indtil denne afspilning er afsluttet, før du anmoder om en ny.

Sørg for, at endpointet er Active, før du afspiller. Hvis endpointet er inaktivt, kan den kølagte afspilning ikke leveres korrekt.

Fordi en modtager kan have gennemført forretningshandlingen, selv om Maildroppa ikke modtog et succes-svar, kan replay medføre en dubleret anmodning. Deduplikering efter Event ID beskytter det forbundne system mod at gentage handlingen.

Redigering af et endpoint

Klik på “Edit” for at ændre URL, hændelsesvalg, brugerdefinerede headere eller aktiv status.

Før du gemmer:

1. Bekræft, at den nye URL allerede er tilgængelig.
2. Lad gemte headerværdier være tomme, når de skal forblive uændrede.
3. Indtast en ny værdi for alle omdøbte headere.
4. Gennemgå hændelsesvalget, så nødvendige underretninger ikke fjernes ved et uheld.
5. Gem, og send en ny Test webhook.

Husk, at leveringer i kø bevarer deres eksisterende URL og øjebliksbillede af brugerdefinerede headere. Test den nye konfiguration for fremtidige leveringer i stedet for at antage, at den ændrer en ældre anmodning i kø.

Deaktivering af et endpoint

Brug On/Off-kontakten, når du vil sætte en integration på pause uden at slette dens konfiguration og historik.

Når et endpoint slås fra:

• Sættes nye hændelser ikke længere i kø til det.
• Markeres Pending-leveringer, der endnu ikke er taget i krav til afsendelse, som Failed.
• Deaktiveres Test.
• Forbliver endpointet tilgængeligt for redigering og senere aktivering.

En anmodning, der allerede er i gang, når deaktiveringen sker, kan stadig blive afsluttet. Kontrollér leveringshistorikken efter at have slået endpointet fra, hvis denne forskel er vigtig for din integration.

Hændelser, der blev overset, mens endpointet var inaktivt, udfyldes ikke, når du slår det til igen.

Sletning af et endpoint

Klik på “Delete”, og bekræft advarslen, når endpointet ikke længere skal eksistere.

Sletning fjerner endpointet fra siden, stopper fremtidige hændelsesleveringer og markerer ventende leveringer, der endnu ikke er taget i krav til afsendelse, som Failed.

Delete er ikke en måde at sætte noget midlertidigt på pause. Brug On/Off-kontakten, når du muligvis får brug for konfigurationen eller den synlige historik igen.

Før sletning skal du notere eventuelle Event ID’er eller Delivery ID’er, som du stadig har brug for til din integrationsrevision.

Fejlfinding

Endpointet kan ikke gemmes

Kontrollér, at:

• URL’en begynder med https://.
• URL’en bruger et offentligt hostname og port 443.
• URL’en ikke indeholder variabler, loginoplysninger eller fragment.
• Mindst én hændelse er valgt.
• Alle Custom headers har et unikt navn og en værdi.
• Reserverede Maildroppa- og HTTP-headere ikke bruges som brugerdefinerede navne.

Test er deaktiveret

Test er kun tilgængelig for et Active-endpoint. Slå endpointet til, eller redigér det, og vælg “Active”. Gem derefter, før du tester.

Test viser ingen HTTP-anmodning

Generér en Signing secret, hvis status er Missing. Kontrollér også, om destinationens hostname er offentligt og stadig peger korrekt.

En anmodning kan afvises før afsendelse, når dens hemmelighed, URL, brugerdefinerede headere eller destinationssikkerhedskontrol er ugyldig.

Modtageren returnerer 401 eller 403

Kontrollér det gemte navn på Custom header og legitimationsoplysningerne. Redigér endpointet, og indtast værdien igen, hvis den er ændret.

Kontrollér også, at modtageren ikke forveksler sin egen API-legitimation med Maildroppa-signaturen. En brugerdefineret Authorization-header og X-Maildroppa-Signature tjener forskellige formål og kan kontrolleres uafhængigt.

Modtageren returnerer en redirect

Maildroppa følger ikke redirects. Erstat endpoint-URL’en med den endelige offentlige HTTPS-URL, og test igen.

Signaturen matcher ikke

Bekræft, at modtageren:

• Bruger den aktuelle Signing secret.
• Bruger den nøjagtige X-Maildroppa-Timestamp-værdi.
• Signerer <timestamp>.<raw request body>.
• Bruger HMAC-SHA256 og output i små bogstaver i hexadecimal form.
• Sammenligner hele værdien inklusive v1=.
• Udfører sammenligningen, før JSON-parsing ændrer body-indholdet.

Den samme hændelse modtages mere end én gang

Det kan ske efter en netværksafbrydelse, et retry eller en manuel afspilning. Det er normalt, at webhook-leveringssystemer leverer mindst én gang i stedet for præcis én gang.

Brug Event ID som idempotensnøgle. Returnér et 2xx-svar, når et allerede behandlet Event ID modtages igen, og der ikke kræves yderligere handling.

En levering er Pending

Se “Next retry” i HTTP-kolonnen. Et retrybart 408-, 429-, 5xx- eller midlertidigt netværksproblem forbliver Pending indtil det næste planlagte forsøg.

Klik på “Refresh” efter retry-tidspunktet for at indlæse den nyeste status.

En levering er Dead

Alle automatiske forsøg er brugt. Afhjælp først problemet hos modtageren, kontrollér, at endpointet er Active, send en Test webhook, og brug derefter Replay på produktionsleveringen.

Anbefalet produktionscheckliste

Før du stoler på et endpoint i produktion, skal du bekræfte alle følgende punkter:

1. Modtageren bruger en stabil offentlig HTTPS-URL med et gyldigt certifikat.
2. Signing secret gemmes uden for kildekoden.
3. Signaturen kontrolleres mod den uændrede rå body.
4. Gamle timestamps afvises i henhold til en dokumenteret tolerance.
5. Modtageren gemmer og deduplikerer Event ID’er.
6. Modtageren logger Event ID’er og Delivery ID’er til sporing.
7. Langsom behandling sker, efter at hændelsen er accepteret permanent.
8. Der returneres et 2xx-svar kun for accepterede hændelser.
9. Brugerdefinerede legitimationsoplysninger gemmes i headere i stedet for URL’en.
10. Kun nødvendige hændelsestyper er valgt.
11. En Test webhook lykkes og vises korrekt i leveringshistorikken.
12. Overvågning alarmerer dig, når produktionsleveringer begynder at returnere fejl.

Med disse sikkerhedsforanstaltninger på plads leverer siden Webhooks begge sider af en pålidelig integration: sikker hændelseslevering til din applikation og en tydelig driftshistorik i Maildroppa.