Konfigurera webhooks

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

Webhooks gör det möjligt för Maildroppa att meddela ett annat program när något viktigt händer i ditt konto.

I stället för att upprepade gånger fråga Maildroppa om en prenumerant har skapats, uppdaterats, avslutat prenumerationen eller tilldelats en tagg kan ditt program ta emot en HTTPS-begäran kort efter att händelsen inträffat.

Sidan Webhooks är den centrala platsen för denna kontoomfattande integration. Du kan skapa flera slutpunkter, välja vilka händelser varje slutpunkt tar emot, lägga till autentiseringsheaders, testa anslutningen, granska leveransförsök och spela upp en produktionshändelse igen vid behov.

Så fungerar webhooks för kontot

En webhook för ett konto följer denna process:

1. En händelse inträffar i Maildroppa, till exempel att en prenumerant skapas.
2. Maildroppa hittar alla aktiva slutpunkter som prenumererar på den händelsen.
3. Maildroppa skapar en leverans för varje matchande slutpunkt.
4. JSON-nyttolasten signeras med kontots Signing secret för webhooks.
5. Maildroppa skickar en HTTPS-POST-begäran till den sparade slutpunkts-URL:en.
6. Din slutpunkt verifierar signaturen, lagrar eller behandlar händelsen och returnerar ett HTTP-svar.
7. Maildroppa registrerar resultatet i leveranshistoriken och försöker automatiskt igen vid tillfälliga fel.

Om flera slutpunkter prenumererar på samma händelse får varje slutpunkt sin egen leverans. Affärshändelsen har samma Event ID för alla, medan varje leverans har ett eget Delivery ID.

Webhooks för kontot skiljer sig från steget ”Send a webhook” i en Automation. Webhooks för kontot lyssnar efter valda kontohändelser i hela Maildroppa. En Automation-webhook skickas endast när en prenumerant når just det steget. Båda använder kontots Signing secret för webhooks, så om du roterar hemligheten påverkas alla utgående webhook-mottagare som verifierar Maildroppas signaturer.

Öppna sidan Webhooks

Öppna ”Settings”, expandera ”Developers” och välj ”Webhooks”.

Sidan innehåller tre huvudområden:

• Signing secret
• Endpoints
• Leveranshistorik för den valda slutpunkten

När du har mer än en slutpunkt väljer du en slutpunktsrad för att visa dess leveranshistorik. Om du inte har valt någon uttryckligen visar Maildroppa historiken för den första slutpunkten i listan.

Innan du skapar en slutpunkt

Förbered en mottagare på din server innan du konfigurerar Maildroppa. Mottagaren bör:

• Vara tillgänglig via en offentlig HTTPS-URL.
• Acceptera POST-begäranden med en application/json-body.
• Bevara den råa request-body:n tills Maildroppas signatur har verifierats.
• Returnera status 2xx först efter att händelsen har accepterats på ett säkert sätt.
• Hantera upprepade leveranser idempotent genom att använda Event ID.
• Svara snabbt i stället för att utföra långsamt arbete under begäran.

Ett tillförlitligt mönster är att verifiera begäran, lagra Event ID och nyttolasten i en beständig kö eller databas, returnera 200 eller 204 och därefter behandla affärsåtgärden.

Exponera inte en utvecklingsdator, en lokal nätverksadress eller ett oskyddat skript som produktionsmottagare för webhooks. Maildroppa accepterar endast offentliga HTTPS-mål och kontrollerar destinationen igen när en leverans skickas.

Steg 1: Generera Signing secret

Varje webhook-begäran från Maildroppa signeras. Din mottagare använder Signing secret för att verifiera att begäran skapades av Maildroppa och att body:n inte ändrades under överföringen.

Högst upp på sidan visar panelen Signing secret ett av följande tillstånd:

• Missing — Det finns ännu ingen Signing secret.
• Ready — En Signing secret är konfigurerad.
• Loading — Maildroppa hämtar aktuell status.

Klicka på ”Generate secret” när statusen är Missing.

Maildroppa visar den nya hemligheten omedelbart. Den börjar med whsec_. Klicka på ”Copy” och lagra den i den secret manager eller skyddade miljökonfiguration som din mottagare använder.

Hela värdet visas endast direkt efter generering eller rotation. När du laddar om sidan eller lämnar den visar Maildroppa endast att en hemlighet finns och när den senast uppdaterades. Den visar inte den lagrade hemligheten igen.

Om du förlorar hemligheten

Om mottagaren inte längre har den aktuella hemligheten klickar du på ”Rotate secret” och sparar det nyvisade värdet.

Rotation ersätter den tidigare hemligheten omedelbart. Maildroppa behåller inte båda värdena under någon övergångsperiod. Uppdatera alla mottagare som använder denna kontohemlighet innan du skickar fler tester eller förlitar dig på produktionsleveranser.

Nya leveranser, schemalagda omförsök, tester och repriser signeras med den aktuella hemligheten vid tidpunkten för HTTP-begäran. Det innebär att en leverans som skapades före rotation fortfarande kan signeras med den nya hemligheten när den försöks skickas senare.

Behandla hemligheten som ett lösenord

Placera inte Signing secret i webbläsarkod, ett offentligt kodarkiv, en URL, en felsida eller en vanlig applikationslogg.

Det är endast mottagaren på serversidan som behöver hemligheten. Om du tror att den har röjts ska du rotera den och omedelbart uppdatera alla mottagare.

Verifiera en webhook-signatur

Varje begäran innehåller följande Maildroppa-headers:

• X-Maildroppa-Event-Id — Identifierar affärshändelsen.
• X-Maildroppa-Delivery-Id — Identifierar just denna leverans.
• X-Maildroppa-Timestamp — Signeringstiden som Unix-sekunder.
• X-Maildroppa-Signature — Den versionsnumrerade HMAC-signaturen.

Maildroppa skickar även:

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

Signaturen har följande format:

v1=<lowercase hexadecimal HMAC>

Maildroppa skapar den med HMAC-SHA256. Det signerade innehållet är tidsstämpeln, följd av en punkt och därefter den exakta råa JSON-request-body:n:

<timestamp>.<raw request body>

Använd Signing secret som HMAC-nyckel.

Följande Node.js-exempel visar det centrala verifieringssteget. rawBody måste vara de ursprungliga bytesen i begäran, inte JSON som redan har parsats och serialiserats 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);
}

När signaturen har verifierats ska du även jämföra tidsstämpeln med serverns tid. Avvisa begäranden som ligger utanför en kort tolerans som valts för din infrastruktur, exempelvis fem minuter. Det minskar risken för att en giltig, infångad begäran spelas upp långt senare.

Parsa och behandla JSON först efter att båda kontrollerna har godkänts.

Vanliga orsaker till signaturfel

En signatur misslyckas vanligtvis av någon av följande orsaker:

• Mottagaren använder en gammal hemlighet efter rotation.
• Middleware parsade eller ändrade JSON innan signaturen beräknades.
• Mottagaren signerar endast body:n och utelämnar <timestamp>..
• Tidsstämpeln behandlas som ett formaterat datum i stället för det exakta header-värdet.
• Prefixet v1= utelämnas vid jämförelsen.
• Den beräknade HMAC-koden kodas på annat sätt än som hexadecimalt med gemener.

Logga Event ID och Delivery ID när verifieringen misslyckas, men logga aldrig Signing secret eller känsliga värden i egna headers.

Steg 2: Lägg till en slutpunkt

Klicka på ”Add endpoint” i avsnittet Endpoints.

Redigeraren innehåller fyra delar:

• Endpoint URL
• Events
• Custom headers
• Aktiv status

Nya slutpunkter startar som aktiva och alla händelser som visas i redigeraren är initialt valda. Granska urvalet innan du sparar så att mottagaren endast får de aviseringar den faktiskt behöver.

Konfigurera slutpunkts-URL:en

Ange den fullständiga offentliga URL som ska ta emot Maildroppas begäranden, till exempel:

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

URL:en måste uppfylla följande krav:

• Den måste använda https://.
• Den måste innehålla ett giltigt offentligt värdnamn.
• Den får vara högst 2 048 tecken lång.
• Den får inte innehålla mallvariabler med { eller }.
• Den får inte innehålla användarnamn eller lösenord före värdnamnet.
• Den får inte innehålla ett URL-fragment som börjar med #.
• Den måste använda HTTPS standardport 443.
• Den får inte använda localhost, en rå IP-adress eller ett värdnamn som pekar på ett blockerat privat eller reserverat nätverk.

Frågeparametrar stöds, men placera inte API-nycklar eller andra hemligheter i URL:en. URL:er syns i slutpunktslistan och leveransdata. Använd i stället en Custom header för autentiseringsuppgifter.

Maildroppa följer inte omdirigeringar. Spara den slutliga HTTPS-destinationen i stället för en URL som returnerar 301, 302, 307 eller 308.

Destinationens värdnamn löses upp igen innan begäran skickas. Ett värdnamn som senare pekar på en privat eller blockerad adress avvisas även om det var giltigt när slutpunkten sparades.

Välj händelser

Välj minst en händelse. En slutpunkt tar endast emot de händelsetyper som valts i dess redigerare.

Sidan erbjuder följande händelsealternativ:

Subscriber Created — subscriber.created

Skickas när en prenumerant skapas i Maildroppa-kontot.

Använd denna händelse för att skapa motsvarande kontakt i ett CRM-system, en kunddataplattform, en intern databas eller ett annat system med hänsyn till behörigheter.

Tolka inte denna händelse som ett bevis på att varje registrering har slutfört Double Opt-in. Prenumerantens status i nyttolasten beskriver det aktuella tillståndet.

Subscriber Updated — subscriber.updated

Skickas när inbyggd prenumerantinformation eller värden i anpassade fält ändras.

Använd det fullständiga prenumerantobjektet i nyttolasten som den aktuella representationen i Maildroppa. Utgå inte från att endast en viss egenskap ändrades.

Taggtilldelningar och borttagningar har egna händelsetyper så att de kan hanteras separat.

Subscriber Unsubscribed — subscriber.unsubscribed

Skickas när prenumeranten övergår till statusen unsubscribed genom en åtgärd för att avsluta prenumerationen.

Använd denna händelse för att blockera kontakten i anslutna system. Prenumerera inte automatiskt på personen igen bara för att ett annat system fortfarande markerar kontakten som aktiv.

Tag Added — subscriber.tag_added

Skickas när en tagg tilldelas en prenumerant.

Nyttolasten innehåller prenumeranten och taggen som ingick i just denna ändring.

Tag Removed — subscriber.tag_removed

Skickas när en tagg tas bort från en prenumerant.

Nyttolasten innehåller den uppdaterade prenumeranten och den borttagna taggen. Den borttagna taggen anges separat även om den inte längre finns i prenumerantens aktuella tags-array.

Form Submitted — form.submitted

Skickas när en besökare skickar in ett registreringsformulär i Maildroppa.

Betrakta detta som en signal om att ett formulär skickats in, inte som en bekräftelse på att Double Opt-in har slutförts. Alla arbetsflöden som kräver en bekräftad prenumeration måste fortsätta att respektera prenumerantens aktuella status och bekräftelseprocessen.

Använd separata slutpunkter när ansvarsområden skiljer sig åt

Du kan skicka olika händelser till olika system. Till exempel:

• Skicka prenumerant- och tagghändelser till ett CRM-system.
• Skicka avslutade prenumerationer till en tjänst för blockering.
• Skicka formulärinsändningar till en analyspipeline.

Separata slutpunkter minskar onödig trafik och gör fel enklare att diagnostisera. Varje slutpunkt har eget händelseurval, URL, egna anpassade headers, aktiv status, tester och leveranshistorik.

Lägg till anpassade headers

Anpassade headers är valfria. Använd dem när mottagaren kräver en API-nyckel, bearer-token, klientidentifierare eller en annan fast header.

Klicka på ”Add header” och ange sedan Header name och Header value. Lämpliga exempel är:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Du kan lägga till upp till 20 anpassade headers.

Header-namn:

• Krävs.
• Kan innehålla upp till 128 tecken.
• Måste använda giltiga tecken för HTTP-headernamn.
• Måste vara unika oberoende av versaler och gemener.

Header-värden:

• Krävs.
• Kan innehålla upp till 2 000 tecken.
• Får inte innehålla radbrytningar.

Följande namn är reserverade och kan inte ersättas av en anpassad header:

• Content-Type
• Content-Length
• Host
• User-Agent
• Alla namn som börjar med X-Maildroppa-

Detta förhindrar att ett anpassat värde ersätter Maildroppas leverans- och signaturheaders.

Så lagras header-hemligheter

Maildroppa krypterar värden i anpassade headers innan de lagras. Sparade värden skickas inte tillbaka till webbläsaren i läsbar form.

När du redigerar slutpunkten senare visar värdefältet ”Stored value kept”. Lämna det tomt när den befintliga hemligheten ska vara oförändrad. Ange ett nytt värde för att ersätta den.

Om du ändrar header-namnet måste du ange värdet igen. Maildroppa behåller en lagrad hemlighet endast så länge det ursprungliga header-namnet är oförändrat.

Om du tar bort en header-rad tas den headern bort från framtida leveranser när slutpunkten har sparats.

Värden i anpassade headers behandlas som känsliga i lagrad request-information. De maskeras i stället för att visas i leveranshistoriken.

Ställ in slutpunkten som aktiv eller inaktiv

Låt ”Active” vara markerat när slutpunkten är redo att ta emot händelser omedelbart.

Avmarkera det när du vill spara konfigurationen utan att börja skicka leveranser. Du kan aktivera slutpunkten senare från slutpunktslistan.

En inaktiv slutpunkt:

• Tar inte emot nya händelser.
• Kan inte skicka en Test webhook.
• Förblir synlig och redigerbar.
• Behåller sin befintliga leveranshistorik.

När en slutpunkt aktiveras fylls inte händelser som inträffade medan den var inaktiv i efterhand.

Klicka på ”Save” när URL, händelseurval, headers och status är korrekta.

Förstå slutpunktslistan

Varje slutpunktsrad visar:

• Destinations-URL:en.
• En Active- eller Inactive-badge.
• De prenumererade händelsetyperna.
• Antalet anpassade headers.
• När slutpunkten senast uppdaterades.

Tillgängliga åtgärder är:

• On/Off — Aktiverar eller inaktiverar slutpunkten.
• Test — Skickar en omedelbar testbegäran till en aktiv slutpunkt.
• Edit — Ändrar URL, händelser, headers eller aktiv status.
• Delete — Tar permanent bort slutpunktskonfigurationen efter bekräftelse.

Välj huvuddelen av en rad för att öppna slutpunktens leveranshistorik under listan.

Så påverkar sparade ändringar befintliga leveranser

En kontohändelse skapar en leverans med en ögonblicksbild av slutpunktens URL, nyttolast och anpassade headers vid den tidpunkten.

Om du redigerar URL eller anpassade headers påverkar det nyskapade leveranser. En leverans som redan ligger i kön behåller sin ursprungliga destination och lagrade header-konfiguration.

Ändringar av valda händelser påverkar också endast händelser som inträffar därefter. Maildroppa skapar inte retroaktiva leveranser för händelsetyper som inte var valda när händelsen inträffade.

Signing secret skiljer sig åt: den läses när HTTP-begäran förbereds. En väntande leverans eller repris kan därför använda en nyligen roterad Signing secret även om dess nyttolast och slutpunktsögonblicksbild skapades tidigare.

Testa en slutpunkt

Klicka på ”Test” för en aktiv slutpunkt när mottagaren och Signing secret är klara.

Maildroppa skickar omedelbart en signerad begäran med den sparade slutpunkts-URL:en och de sparade anpassade headers. Osparade ändringar i en öppen redigerare ingår inte i testet.

Testnyttolasten använder händelsetypen webhook.test och anger livemode till 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 genererade ID:na och tidsstämpeln skiljer sig åt för varje verkligt test.

Ett test gör exakt ett HTTP-försök. Testleveranser läggs inte in i produktionsschemat för omförsök och kan inte spelas upp igen.

När begäran är klar visar resultatpanelen:

• Test success eller Test failed
• Event ID
• HTTP-status när ett svar togs emot
• Varaktighet
• Delivery ID
• Felinformation när sådan finns
• Ett utdrag av svaret när mottagaren returnerade en body

Testet visas även i leveranshistoriken med en Test-badge. Använd filtret ”Test” för att endast visa testbegäranden.

Förstå produktionsnyttolasten

Produktionshändelser för kontot använder ett gemensamt JSON-kuvert:

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

Egenskaperna på toppnivå betyder:

• id — Event ID. Det matchar X-Maildroppa-Event-Id.
• type — Den händelsenyckel som valts i slutpunktsredigeraren.
• schema_version — Nyttolastens schemaversion. Använd den när du avgör hur händelsen ska parsas.
• created_at — Tiden då händelsens nyttolast skapades, i UTC.
• livemode — true för produktionshändelser och false för testhändelser.
• data — Det händelsespecifika innehållet.

Dirigera händelser efter det exakta värdet för type. Ignorera ytterligare egenskaper som integrationen inte behöver, så att kompatibla tillägg i nyttolasten inte får mottagaren att sluta fungera.

Nyttolast för prenumeranthändelser

Prenumeranthändelser innehåller den aktuella representationen av prenumeranten 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 och tags är arrayer. De kan vara tomma. En egenskap hos en prenumerant kan också vara null när inget värde finns, så mottagaren bör följa nyttolastens schema i stället för att anta att alla valfria profilvärden finns.

Nyttolast för tagghändelser

Tagghändelser innehåller både prenumeranten och taggen som orsakade 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"
    }
  }
}

För subscriber.tag_removed identifierar data.tag fortfarande den borttagna taggen även om prenumerantens aktuella tags-array inte längre innehåller den.

Event ID, Delivery ID och idempotens

Event ID och Delivery ID har olika syften.

Event ID

Event ID identifierar affärshändelsen. Det finns i:

• Nyttolastens id-egenskap på toppnivå.
• Request-headern X-Maildroppa-Event-Id.
• Leveranshistoriken.

Samma händelse kan skickas till flera prenumererande slutpunkter. Dessa leveranser delar Event ID.

Omförsök och manuella repriser behåller också det ursprungliga Event ID:t. Lagra behandlade Event ID:n och gör affärsåtgärden idempotent så att en upprepad begäran inte skapar dubbla kontakter, upprepar en oåterkallelig åtgärd eller tillämpar samma ändring två gånger.

Delivery ID

Delivery ID identifierar en leveranspost. Det finns i:

• Request-headern X-Maildroppa-Delivery-Id.
• Leveranshistoriken.

Varje slutpunktsleverans har sitt eget Delivery ID. En manuell repris skapar ett nytt Delivery ID men behåller det ursprungliga Event ID:t.

Använd Delivery ID för teknisk spårning och support. Använd Event ID för deduplicering på affärsnivå.

Returnera korrekt HTTP-svar

Maildroppa klassificerar svar på följande sätt:

• Alla 2xx-svar markerar leveransen som lyckad.
• 408 Request Timeout, 429 Too Many Requests och 5xx-svar är tillfälliga fel och kan försöka skickas igen.
• Nätverksfel som kan vara tillfälliga försöks igen.
• Omdirigeringar och andra 3xx-svar följs inte och behandlas som slutgiltiga fel.
• Övriga 4xx-svar behandlas som slutgiltiga fel och försöks inte igen.

Returnera 200, 202 eller 204 endast när händelsen har accepterats på ett säkert sätt. Om behandlingen tar tid ska du först lagra händelsen och returnera ett lyckat svar innan det långsammare arbetet utförs asynkront.

Returnera inte en omdirigering till en annan webhook-URL. Konfigurera den slutliga URL:en i Maildroppa i stället.

Automatiskt schema för omförsök

Produktionsleveranser kan göra upp till sju HTTP-försök.

Efter ett fel som kan försöka igen schemalägger Maildroppa nästa försök med följande fördröjningar:

1. Efter försök 1: 1 minut
2. Efter försök 2: 5 minuter
3. Efter försök 3: 30 minuter
4. Efter försök 4: 2 timmar
5. Efter försök 5: 12 timmar
6. Efter försök 6: 24 timmar

Om försök 7 fortfarande får ett fel som kan försöka igen blir leveransen Dead och inget ytterligare automatiskt försök schemaläggs.

Schemat mäts från de enskilda misslyckade försöken. Den faktiska leveranstiden kan bli något senare eftersom leveranser behandlas asynkront och även omfattas av systemets skyddsgränser.

Åtgärda ett tillfälligt problem hos mottagaren före den visade tiden för ”Next retry” när det är möjligt. När de automatiska försöken har avslutats använder du Replay efter att mottagaren fungerar igen.

Förstå leveranshistoriken

Leveranshistoriken tillhör den slutpunkt som för närvarande är vald. Slutpunkts-URL:en visas i sektionsrubriken så att du kan bekräfta vilken historik du visar.

Använd dessa filter:

• All — Visar produktions- och testleveranser.
• Production — Visar endast aktiva händelseleveranser.
• Test — Visar endast manuella tester.

Klicka på ”Refresh” för att hämta det senaste tillståndet. Historiken behöver inte vara öppen medan Maildroppa skickar eller försöker skicka en leverans igen.

Sidan visar de senaste 50 matchande leveranserna för det valda filtret.

Leveranskolumner

Varje rad innehåller:

• Created — När leveransposten skapades.
• State — Pending, Success, Failed eller Dead.
• HTTP — Svarstatus, antal försök och varaktighet samt nästa omförsökstid när det är relevant.
• Subscriber — Prenumerantens e-postadress när händelsen är kopplad till en prenumerant.
• Delivery — Händelsetyp, Event ID och Delivery ID.
• Actions — Replay när leveransen kan spelas upp igen.

Om inget HTTP-anrop gjordes visar HTTP-kolumnen ”No HTTP attempt”. Det kan hända när Maildroppa avvisar begäran innan den skickas, till exempel för att Signing secret saknas eller för att den sparade destinationen inte längre kan användas säkert.

När det finns tillgängligt visar raden även ett Error och ett Response excerpt som mottagaren returnerat. Returnera inte hemligheter eller känsliga personuppgifter i en webhook-svarskropp eftersom en del av svaret kan visas i kontots leveranslogg.

Leveranstillstånd

Pending innebär att leveransen väntar på sitt första försök eller ett schemalagt omförsök. ”Next retry” visas när ytterligare ett försök har schemalagts.

Success innebär att mottagaren returnerade ett 2xx-svar. Inget ytterligare automatiskt försök krävs.

Failed innebär att leveransen avslutades på grund av ett problem som inte kan försöka igen, avvisades före ett HTTP-försök eller stoppades innan den kunde skickas.

Dead innebär att alla automatiska försök för ett problem som kan försöka igen har använts utan att ett lyckat svar tagits emot.

Bevarande av historik

Leveransposter sparas under en begränsad tid:

• Lyckade produktionsleveranser: 30 dagar
• Misslyckade produktionsleveranser: 90 dagar
• Dead-produktionsleveranser: 90 dagar
• Testleveranser: 30 dagar

Förvara egna integrationsloggar när du behöver en längre revisionshistorik. Lagra Event ID och Delivery ID, men undvik att lagra hemligheter i onödan.

Spela upp en leverans igen

Klicka på ”Replay” när en slutförd produktionsleverans ska försöka skickas igen.

Replay är tillgängligt för produktionsleveranser i tillstånden Success, Failed eller Dead. Det är inte tillgängligt medan en leverans är Pending, och testleveranser kan inte spelas upp igen.

En repris:

• Skapar en ny Pending-leverans.
• Skapar ett nytt Delivery ID.
• Behåller det ursprungliga Event ID:t.
• Behåller den ursprungliga händelsetypen och JSON-nyttolasten.
• Använder den ursprungliga sparade mål-URL:en och ögonblicksbilden av anpassade headers.
• Använder den aktuella Signing secret när den nya begäran förbereds.

Replay bygger inte om nyttolasten från prenumerantens aktuella data. Den skickar den ursprungliga händelseögonblicksbilden igen. Det gör reprisen spårbar och förhindrar att en historisk händelse i det tysta ändrar innebörd.

Endast en repris av samma källleverans kan vara Pending åt gången. Vänta tills reprisen är klar innan du begär en ny.

Se till att slutpunkten är Active innan du spelar upp den igen. Om slutpunkten är inaktiv kan den köade reprisen inte levereras korrekt.

Eftersom en mottagare kan ha slutfört affärsåtgärden även när Maildroppa inte tog emot dess lyckade svar kan en repris skapa en dubblerad begäran. Deduplicering med Event ID skyddar det anslutna systemet från att upprepa åtgärden.

Redigera en slutpunkt

Klicka på ”Edit” för att ändra URL, händelseurval, anpassade headers eller aktiv status.

Innan du sparar:

1. Bekräfta att den nya URL:en redan är tillgänglig.
2. Lämna lagrade header-värden tomma när de ska vara oförändrade.
3. Ange ett nytt värde för varje omdöpt header.
4. Granska händelseurvalet så att nödvändiga aviseringar inte tas bort av misstag.
5. Spara och skicka en ny Test webhook.

Kom ihåg att köade leveranser behåller sin befintliga URL och ögonblicksbild av anpassade headers. Testa den nya konfigurationen för framtida leveranser i stället för att anta att den ändrar en äldre köad begäran.

Inaktivera en slutpunkt

Använd reglaget On/Off när du vill pausa en integration utan att ta bort dess konfiguration och historik.

När en slutpunkt stängs av:

• Köas inga nya händelser för den.
• Markeras väntande leveranser som ännu inte har hämtats för sändning som Failed.
• Inaktiveras Test.
• Förblir slutpunkten tillgänglig för redigering och senare aktivering.

En begäran som redan pågår när slutpunkten inaktiveras kan fortfarande slutföras. Kontrollera leveranshistoriken efter att du stängt av slutpunkten om denna skillnad är viktig för din integration.

Händelser som missas medan slutpunkten är inaktiv fylls inte i efterhand när du aktiverar den igen.

Ta bort en slutpunkt

Klicka på ”Delete” och bekräfta varningen när slutpunkten inte längre ska finnas.

När du tar bort slutpunkten försvinner den från sidan, framtida händelseleveranser stoppas och väntande leveranser som ännu inte har hämtats för sändning markeras som Failed.

Delete är inte ett sätt att pausa tillfälligt. Använd reglaget On/Off när du kan behöva konfigurationen eller dess synliga historik igen.

Innan du tar bort slutpunkten bör du anteckna eventuella Event ID eller Delivery ID som du fortfarande behöver för integrationsrevisionen.

Felsökning

Det går inte att spara slutpunkten

Kontrollera att:

• URL:en börjar med https://.
• URL:en använder ett offentligt värdnamn och port 443.
• URL:en inte innehåller variabler, inloggningsinformation eller fragment.
• Minst en händelse är vald.
• Varje Custom header har ett unikt namn och ett värde.
• Reserverade Maildroppa- och HTTP-headers inte används som anpassade namn.

Test är inaktiverat

Test är endast tillgängligt för en Active-slutpunkt. Aktivera slutpunkten eller redigera den och välj ”Active”. Spara sedan innan du testar.

Testet visar inget HTTP-försök

Generera en Signing secret om statusen är Missing. Kontrollera även om destinationsvärdnamnet är offentligt och fortfarande pekar rätt.

En begäran kan avvisas innan den skickas när dess hemlighet, URL, anpassade headers eller säkerhetskontroll av destinationen är ogiltig.

Mottagaren returnerar 401 eller 403

Kontrollera den sparade Custom headerns namn och autentiseringsuppgift. Redigera slutpunkten och ange värdet igen om det har ändrats.

Kontrollera också att mottagaren inte blandar ihop sin egen API-autentisering med Maildroppa-signaturen. En anpassad Authorization-header och X-Maildroppa-Signature har olika syften och kan kontrolleras separat.

Mottagaren returnerar en omdirigering

Maildroppa följer inte omdirigeringar. Ersätt slutpunkts-URL:en med den slutliga offentliga HTTPS-URL:en och testa igen.

Signaturen matchar inte

Bekräfta att mottagaren:

• Använder den aktuella Signing secret.
• Använder det exakta värdet i X-Maildroppa-Timestamp.
• Signerar <timestamp>.<raw request body>.
• Använder HMAC-SHA256 och hexadecimalt resultat med gemener.
• Jämför hela värdet inklusive v1=.
• Utför jämförelsen innan JSON-parsning ändrar body:n.

Samma händelse kommer mer än en gång

Det kan hända efter ett nätverksavbrott, ett omförsök eller en manuell repris. Det är normalt att webhook-leveranssystem erbjuder leverans minst en gång i stället för exakt en gång.

Använd Event ID som idempotensnyckel. Returnera ett 2xx-svar när ett redan behandlat Event ID tas emot igen och ingen ytterligare åtgärd behövs.

En leverans är Pending

Titta på ”Next retry” i HTTP-kolumnen. Ett omförsöksbart 408-, 429-, 5xx- eller tillfälligt nätverksfel förblir Pending fram till nästa schemalagda försök.

Klicka på ”Refresh” efter omförsökstiden för att läsa in det senaste tillståndet.

En leverans är Dead

Alla automatiska försök har använts. Åtgärda mottagaren först, kontrollera att slutpunkten är Active, skicka en Test webhook och använd sedan Replay på produktionsleveransen.

Rekommenderad checklista för produktion

Innan du förlitar dig på en slutpunkt i produktion ska du bekräfta allt följande:

1. Mottagaren använder en stabil offentlig HTTPS-URL med ett giltigt certifikat.
2. Signing secret lagras utanför källkoden.
3. Signaturen kontrolleras mot den oförändrade råa body:n.
4. Gamla tidsstämplar avvisas enligt en dokumenterad tolerans.
5. Mottagaren lagrar och deduplicerar Event ID.
6. Mottagaren loggar Event ID och Delivery ID för spårning.
7. Långsam behandling sker efter att händelsen har accepterats beständigt.
8. Ett 2xx-svar returneras endast för accepterade händelser.
9. Anpassade autentiseringsuppgifter lagras i headers i stället för i URL:en.
10. Endast nödvändiga händelsetyper är valda.
11. En Test webhook lyckas och visas korrekt i leveranshistoriken.
12. Övervakning varnar dig när produktionsleveranser börjar returnera fel.

Med dessa skydd på plats tillhandahåller sidan Webhooks båda delarna av en tillförlitlig integration: säker händelseleverans till ditt program och en tydlig driftshistorik i Maildroppa.