Määritä webhookit

Published: 16. heinäkuuta 2026 · Last updated: 21. heinäkuuta 2026 · By Marcus Biel

Webhookien avulla Maildroppa voi ilmoittaa toiselle sovellukselle, kun tililläsi tapahtuu jotain tärkeää.

Sen sijaan että sovelluksesi kysyisi toistuvasti Maildroppalta, luotiinko tilaaja, päivitettiinkö sitä, peruutettiinko tilaus tai määritettiinkö tilaajalle tunniste, sovelluksesi voi vastaanottaa HTTPS-pyynnön pian tapahtuman jälkeen.

Webhooks-sivu on tämän koko tiliä koskevan integraation keskeinen paikka. Voit luoda useita päätepisteitä, valita kunkin päätepisteen vastaanottamat tapahtumat, lisätä todennusotsikoita, testata yhteyden, tarkastella toimitusyrityksiä ja toistaa tuotantotapahtuman tarvittaessa.

Tilin webhookien toiminta

Tilin webhook etenee seuraavasti:

1. Maildroppassa tapahtuu tapahtuma, kuten tilaajan luominen.
2. Maildroppa etsii kaikki aktiiviset päätepisteet, jotka on tilattu kyseiseen tapahtumaan.
3. Maildroppa luo jokaiselle vastaavalle päätepisteelle yhden toimituksen.
4. JSON-hyötykuorma allekirjoitetaan tilisi webhookien allekirjoitussalaisuudella.
5. Maildroppa lähettää tallennettuun päätepisteen URL-osoitteeseen HTTPS-POST-pyynnön.
6. Päätepisteesi tarkistaa allekirjoituksen, tallentaa tai käsittelee tapahtuman ja palauttaa HTTP-vastauksen.
7. Maildroppa tallentaa tuloksen toimitushistoriaan ja yrittää tilapäisesti epäonnistuneita toimituksia automaattisesti uudelleen.

Jos useita päätepisteitä on tilattu samaan tapahtumaan, jokainen päätepiste vastaanottaa oman toimituksensa. Liiketoimintatapahtumalla on sama tapahtumatunnus kaikille toimituksille, mutta jokaisella toimituksella on oma toimitustunnuksensa.

Tilin webhookit eroavat automaation sisällä olevasta “Send a webhook” -vaiheesta. Tilin webhookit kuuntelevat Maildroppan valittuja tilitapahtumia. Automaation webhook lähetetään vain, kun tilaaja saavuttaa kyseisen vaiheen. Molemmat käyttävät tilin webhookien allekirjoitussalaisuutta, joten salaisuuden vaihtaminen vaikuttaa kaikkiin lähteviin webhook-vastaanottimiin, jotka tarkistavat Maildroppan allekirjoituksia.

Webhooks-sivun avaaminen

Avaa “Settings”, laajenna “Developers” ja valitse “Webhooks”.

Sivulla on kolme pääaluetta:

• Allekirjoitussalaisuus
• Päätepisteet
• Valitun päätepisteen toimitushistoria

Kun päätepisteitä on useampi kuin yksi, valitse päätepisterivi nähdäksesi sen toimitushistorian. Jos et ole valinnut päätepistettä erikseen, Maildroppa näyttää luettelon ensimmäisen päätepisteen historian.

Ennen päätepisteen luomista

Valmistele vastaanotin palvelimellesi ennen Maildroppan määrittämistä. Vastaanottimen tulisi:

• Olla käytettävissä julkisen HTTPS-URL-osoitteen kautta.
• Hyväksyä POST-pyyntöjä, joiden runko on application/json-muodossa.
• Säilyttää pyyntöjen raakasisältö, kunnes Maildroppan allekirjoitus on tarkistettu.
• Palauttaa 2xx-statuskoodin vasta, kun tapahtuma on hyväksytty turvallisesti.
• Käsitellä toistuvat toimitukset idempotentisti tapahtumatunnuksen avulla.
• Vastata nopeasti sen sijaan, että suorittaisi pyynnön aikana hitaita toimintoja.

Luotettava toimintamalli on tarkistaa pyyntö, tallentaa tapahtumatunnus ja hyötykuorma pysyvään jonoon tai tietokantaan, palauttaa 200 tai 204 ja käsitellä liiketoimintatoiminto sen jälkeen.

Älä altista kehitystietokonetta, paikallisverkon osoitetta tai suojaamatonta komentosarjaa tuotannon webhook-vastaanottimeksi. Maildroppa hyväksyy vain julkiset HTTPS-kohteet ja tarkistaa kohteen uudelleen toimitusta lähetettäessä.

Vaihe 1: allekirjoitussalaisuuden luominen

Jokainen Maildroppan webhook-pyyntö allekirjoitetaan. Vastaanottimesi käyttää allekirjoitussalaisuutta varmistaakseen, että Maildroppa loi pyynnön eikä runkoa muutettu siirron aikana.

Sivun yläreunassa allekirjoitussalaisuuspaneelissa näkyy jokin seuraavista tiloista:

• Missing — Allekirjoitussalaisuutta ei ole vielä luotu.
• Ready — Allekirjoitussalaisuus on määritetty.
• Loading — Maildroppa hakee nykyistä tilaa.

Napsauta “Generate secret”, kun tila on Missing.

Maildroppa näyttää uuden salaisuuden heti. Se alkaa merkkijonolla whsec_. Napsauta “Copy” ja tallenna se salaisuuksien hallintajärjestelmään tai vastaanottimesi suojattuun ympäristömääritykseen.

Koko arvo näytetään vain heti luomisen tai vaihtamisen jälkeen. Kun lataat sivun uudelleen tai poistut siltä, Maildroppa näyttää vain, että salaisuus on olemassa ja milloin se päivitettiin viimeksi. Tallennettua salaisuutta ei näytetä uudelleen.

Jos kadotat salaisuuden

Jos vastaanottimella ei enää ole nykyistä salaisuutta, napsauta “Rotate secret” ja tallenna uusi näytetty arvo.

Vaihtaminen korvaa aiemman salaisuuden heti. Maildroppa ei säilytä molempia arvoja siirtymäaikaa varten. Päivitä kaikki tätä tilin salaisuutta käyttävät vastaanottimet ennen uusien testien lähettämistä tai tuotantotoimituksiin luottamista.

Uudet toimitukset, ajoitetut uudelleenyritykset, testit ja toistot allekirjoitetaan sillä hetkellä voimassa olevalla salaisuudella, kun HTTP-pyyntö luodaan. Tämä tarkoittaa, että ennen vaihtamista luotu toimitus voidaan allekirjoittaa uudella salaisuudella, kun sitä yritetään lähettää myöhemmin.

Käsittele salaisuutta kuin salasanaa

Älä sijoita allekirjoitussalaisuutta selaimen koodiin, julkiseen repositorioon, URL-osoitteeseen, virhesivulle tai tavalliseen sovelluslokiin.

Vain palvelinpuolen vastaanotin tarvitsee salaisuuden. Jos uskot sen paljastuneen, vaihda se ja päivitä kaikki vastaanottimet heti.

Webhook-allekirjoituksen tarkistaminen

Jokainen pyyntö sisältää seuraavat Maildroppa-otsikot:

• X-Maildroppa-Event-Id — Tunnistaa liiketoimintatapahtuman.
• X-Maildroppa-Delivery-Id — Tunnistaa kyseisen toimituksen.
• X-Maildroppa-Timestamp — Allekirjoitusaika Unix-sekunteina.
• X-Maildroppa-Signature — Versioitu HMAC-allekirjoitus.

Maildroppa lähettää myös:

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

Allekirjoituksen muoto on:

v1=<lowercase hexadecimal HMAC>

Maildroppa luo allekirjoituksen HMAC-SHA256:lla. Allekirjoitettava sisältö on aikaleima, piste ja täsmälleen alkuperäinen JSON-pyynnön raakasisältö:

<timestamp>.<raw request body>

Käytä allekirjoitussalaisuutta HMAC-avaimena.

Seuraava Node.js-esimerkki näyttää olennaisen tarkistusvaiheen. rawBody-muuttujan on sisällettävä alkuperäiset pyynnön tavut, ei JSONia, joka on jo jäsennetty ja sarjoitettu uudelleen.

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

Kun allekirjoitus on tarkistettu, vertaa myös aikaleimaa palvelimesi aikaan. Hylkää pyynnöt infrastruktuurillesi määritetyn lyhyen toleranssin ulkopuolelta, esimerkiksi viiden minuutin jälkeen. Tämä vähentää riskiä, että kaapattu kelvollinen pyyntö toistetaan paljon myöhemmin.

Jäsennä ja käsittele JSON vasta, kun molemmat tarkistukset ovat onnistuneet.

Allekirjoitusvirheiden yleiset syyt

Allekirjoitus epäonnistuu yleensä jostakin seuraavista syistä:

• Vastaanotin käyttää vanhaa salaisuutta vaihtamisen jälkeen.
• Middleware jäsensi tai muutti JSONia ennen allekirjoituksen laskemista.
• Vastaanotin allekirjoittaa vain rungon ja jättää <timestamp>.-osan pois.
• Aikaleimaa käsitellään muotoiltuna päivämääränä tarkan otsikkoarvon sijaan.
• v1=-etuliite puuttuu vertailusta.
• Laskettu HMAC on koodattu muulla tavalla kuin pienillä heksadesimaaleilla.

Kirjaa tapahtumatunnus ja toimitustunnus, kun tarkistus epäonnistuu, mutta älä koskaan kirjaa allekirjoitussalaisuutta tai arkaluonteisia mukautettujen otsikoiden arvoja.

Vaihe 2: päätepisteen lisääminen

Napsauta “Add endpoint” Päätepisteet-osiossa.

Muokkain sisältää neljä osaa:

• Päätepisteen URL
• Tapahtumat
• Mukautetut otsikot
• Aktiivinen tila

Uudet päätepisteet ovat aluksi aktiivisia, ja kaikki muokkaimessa näkyvät tapahtumat on aluksi valittu. Tarkista valinta ennen tallentamista, jotta vastaanotin saa vain tarvitsemansa ilmoitukset.

Päätepisteen URL-osoitteen määrittäminen

Syötä täydellinen julkinen URL-osoite, johon Maildroppan pyynnöt vastaanotetaan, esimerkiksi:

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

URL-osoitteen on täytettävä seuraavat vaatimukset:

• Sen on käytettävä https://.
• Sen on sisällettävä kelvollinen julkinen isäntänimi.
• Se voi olla enintään 2 048 merkkiä pitkä.
• Se ei saa sisältää mallimuuttujia, joissa on { tai }.
• Se ei saa sisältää käyttäjänimeä tai salasanaa ennen isäntänimeä.
• Se ei saa sisältää #-merkillä alkavaa URL-fragmenttia.
• Sen on käytettävä HTTPS:n vakiomuotoista porttia 443.
• Se ei saa käyttää localhost-osoitetta, raakaa IP-osoitetta tai isäntänimeä, joka ohjautuu estettyyn yksityiseen tai varattuun verkkoon.

Kyselyparametreja tuetaan, mutta älä sijoita API-avaimia tai muita salaisuuksia URL-osoitteeseen. URL-osoitteet näkyvät päätepisteluettelossa ja toimitustiedoissa. Käytä tunnistetiedoille sen sijaan mukautettua otsikkoa.

Maildroppa ei seuraa uudelleenohjauksia. Tallenna lopullinen HTTPS-kohde URL-osoitteen sijaan, joka palauttaa 301-, 302-, 307- tai 308-vastauksen.

Kohteen isäntänimi selvitetään uudelleen ennen lähettämistä. Isäntänimi, joka myöhemmin ohjautuu yksityiseen tai estettyyn osoitteeseen, hylätään, vaikka se olisi ollut kelvollinen päätepistettä tallennettaessa.

Tapahtumien valitseminen

Valitse vähintään yksi tapahtuma. Päätepiste vastaanottaa vain ne tapahtumatyypit, jotka on valittu sen muokkaimessa.

Sivulla on seuraavat tapahtumavaihtoehdot:

Subscriber Created — subscriber.created

Lähetetään, kun Maildroppa-tilille luodaan tilaaja.

Tämän tapahtuman avulla voit luoda vastaavan yhteyshenkilön CRM:ään, asiakastietoalustaan, sisäiseen tietokantaan tai muuhun käyttöoikeudet huomioivaan järjestelmään.

Älä tulkitse tätä tapahtumaa todisteeksi siitä, että jokainen liittyminen on suorittanut Double Opt-in -vahvistuksen. Hyötykuorman tilaajakenttä kuvaa nykyistä tilaa.

Subscriber Updated — subscriber.updated

Lähetetään, kun tilaajan sisäänrakennetut tiedot tai mukautettujen kenttien arvot muuttuvat.

Käytä hyötykuorman täydellistä tilaajaobjektia nykyisenä Maildroppa-esityksenä. Älä oleta, että vain yksi tietty ominaisuus muuttui.

Tunnisteiden lisäämisellä ja poistamisella on omat tapahtumatyyppinsä, joten niitä voidaan käsitellä erikseen.

Subscriber Unsubscribed — subscriber.unsubscribed

Lähetetään, kun tilaaja siirtyy tilauksen peruuttaneeseen tilaan peruutustoiminnon kautta.

Tämän tapahtuman avulla voit estää yhteyshenkilön käsittelyn yhdistetyissä järjestelmissä. Älä tilaa henkilöä automaattisesti uudelleen vain siksi, että toinen järjestelmä pitää yhteyshenkilöä edelleen aktiivisena.

Tag Added — subscriber.tag_added

Lähetetään, kun tilaajalle määritetään tunniste.

Hyötykuorma sisältää kyseiseen muutokseen liittyvän tilaajan ja tunnisteen.

Tag Removed — subscriber.tag_removed

Lähetetään, kun tunniste poistetaan tilaajalta.

Hyötykuorma sisältää päivitetyn tilaajan ja poistetun tunnisteen. Poistettu tunniste toimitetaan erikseen, vaikka sitä ei enää ole tilaajan nykyisessä tags-taulukossa.

Form Submitted — form.submitted

Lähetetään, kun kävijä lähettää Maildroppa-liittymislomakkeen.

Käsittele tätä lomakkeen lähetyssignaalina, ei vahvistuksena Double Opt-in -prosessin suorittamisesta. Työnkulun, joka edellyttää vahvistettua tilausta, on edelleen huomioitava tilaajan nykyinen tila ja vahvistusprosessi.

Käytä erillisiä päätepisteitä, kun vastuut eroavat

Voit lähettää eri tapahtumia eri järjestelmiin. Esimerkiksi:

• Lähetä tilaaja- ja tunnistetapahtumat CRM-järjestelmään.
• Lähetä tilauksen peruutustapahtumat estopalveluun.
• Lähetä lomakkeen lähetystapahtumat analytiikkaputkeen.

Erilliset päätepisteet vähentävät tarpeetonta liikennettä ja helpottavat virheiden diagnosointia. Jokaisella päätepisteellä on oma tapahtumavalintansa, URL-osoitteensa, mukautetut otsikkonsa, aktiivinen tilansa, testinsä ja toimitushistoriansa.

Mukautettujen otsikoiden lisääminen

Mukautetut otsikot ovat valinnaisia. Käytä niitä, kun vastaanotin edellyttää API-avainta, bearer-tokenia, vuokraajatunnistetta tai muuta kiinteää otsikkoa.

Napsauta “Add header” ja syötä otsikon nimi ja arvo. Sopivia esimerkkejä ovat:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Voit lisätä enintään 20 mukautettua otsikkoa.

Otsikoiden nimet:

• Ovat pakollisia.
• Voivat sisältää enintään 128 merkkiä.
• Niissä on käytettävä kelvollisia HTTP-otsikon nimimerkkejä.
• Niiden on oltava yksilöllisiä kirjainkoosta riippumatta.

Otsikoiden arvot:

• Ovat pakollisia.
• Voivat sisältää enintään 2 000 merkkiä.
• Eivät saa sisältää rivinvaihtoja.

Seuraavat nimet ovat varattuja, eikä niitä voi korvata mukautetulla otsikolla:

• Content-Type
• Content-Length
• Host
• User-Agent
• Mikä tahansa nimi, joka alkaa merkkijonolla X-Maildroppa-

Näin mukautettu arvo ei voi korvata Maildroppan toimitus- ja allekirjoitusotsikoita.

Otsikoiden salaisuuksien tallennus

Maildroppa salaa mukautettujen otsikoiden arvot ennen niiden tallentamista. Tallennettuja arvoja ei palauteta selaimelle luettavassa muodossa.

Kun muokkaat päätepistettä myöhemmin, arvokentässä näkyy “Stored value kept”. Jätä se tyhjäksi, jos nykyisen salaisuuden tulee säilyä ennallaan. Syötä uusi arvo, jos haluat korvata sen.

Jos muutat otsikon nimeä, syötä arvo uudelleen. Maildroppa säilyttää tallennetun salaisuuden vain niin kauan kuin alkuperäinen otsikon nimi pysyy muuttumattomana.

Otsikkorivin poistaminen poistaa kyseisen otsikon tulevista toimituksista, kun päätepiste on tallennettu.

Mukautettujen otsikoiden arvoja käsitellään arkaluonteisina tallennetuissa pyynnön tiedoissa. Ne peitetään sen sijaan, että ne näytettäisiin toimitushistoriassa.

Päätepisteen asettaminen aktiiviseksi tai passiiviseksi

Pidä “Active” valittuna, kun päätepiste on valmis vastaanottamaan tapahtumia heti.

Poista valinta, kun haluat tallentaa määrityksen aloittamatta toimituksia. Voit aktivoida päätepisteen myöhemmin päätepisteluettelosta.

Passiivinen päätepiste:

• Ei vastaanota uusia tapahtumia.
• Ei voi lähettää Test webhookia.
• Pysyy näkyvänä ja muokattavana.
• Säilyttää aiemman toimitushistoriansa.

Päätepisteen aktivointi ei täydennä automaattisesti tapahtumia, jotka tapahtuivat sen ollessa passiivinen.

Napsauta “Save”, kun URL-osoite, tapahtumavalinta, otsikot ja tila ovat oikein.

Päätepisteluettelon ymmärtäminen

Jokaisella päätepisterivillä näkyy:

• Kohteen URL-osoite.
• Active- tai Inactive-merkintä.
• Tilatut tapahtumatyypit.
• Mukautettujen otsikoiden määrä.
• Aika, jolloin päätepiste päivitettiin viimeksi.

Käytettävissä olevat toiminnot ovat:

• On/Off — Aktivoi tai deaktivoi päätepisteen.
• Test — Lähettää yhden välittömän testipyynnön aktiiviseen päätepisteeseen.
• Edit — Muuttaa URL-osoitetta, tapahtumia, otsikoita tai aktiivista tilaa.
• Delete — Poistaa päätepistemäärityksen pysyvästi vahvistuksen jälkeen.

Valitse rivin pääosa avataksesi kyseisen päätepisteen toimitushistorian luettelon alapuolella.

Tallennettujen muutosten vaikutus olemassa oleviin toimituksiin

Tilin tapahtuma luo toimituksen, joka sisältää kyseisellä hetkellä tallennetun tilannekuvan päätepisteen URL-osoitteesta, hyötykuormasta ja mukautetuista otsikoista.

URL-osoitteen tai mukautettujen otsikoiden muokkaaminen vaikuttaa uusiin toimituksiin. Jo jonossa oleva toimitus säilyttää alkuperäisen kohteen ja tallennetun otsikkomäärityksen.

Valittujen tapahtumien muuttaminen vaikuttaa myös vain sen jälkeen tapahtuviin tapahtumiin. Maildroppa ei luo takautuvasti toimituksia tapahtumatyypeille, joita ei ollut valittu tapahtuman sattuessa.

Allekirjoitussalaisuus toimii eri tavalla: se luetaan HTTP-pyyntöä valmisteltaessa. Odottava toimitus tai toisto voi siksi käyttää äskettäin vaihdettua allekirjoitussalaisuutta, vaikka sen hyötykuorma ja päätepisteen tilannekuva olisi luotu aiemmin.

Päätepisteen testaaminen

Napsauta “Test” aktiivisessa päätepisteessä, kun vastaanotin ja allekirjoitussalaisuus ovat valmiina.

Maildroppa lähettää heti yhden allekirjoitetun pyynnön käyttäen tallennettua päätepisteen URL-osoitetta ja tallennettuja mukautettuja otsikoita. Avoimessa muokkaimessa olevat tallentamattomat muutokset eivät sisälly testiin.

Testihyötykuorma käyttää tapahtumatyyppiä webhook.test ja asettaa livemode-arvoksi 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."
  }
}

Luodut tunnukset ja aikaleima ovat erilaiset jokaisessa oikeassa testissä.

Testi tekee täsmälleen yhden HTTP-yrityksen. Testitoimituksia ei lisätä tuotannon uudelleenyritysaikatauluun, eikä niitä voi toistaa.

Kun pyyntö on valmis, tulospaneelissa näkyy:

• Test success tai Test failed
• Tapahtumatunnus
• HTTP-status, kun vastaus vastaanotettiin
• Kesto
• Toimitustunnus
• Virhetiedot, kun niitä on saatavilla
• Vastausote, kun vastaanotin palautti rungon

Testi näkyy myös toimitushistoriassa Test-merkinnällä. Käytä “Test”-suodatinta näyttääksesi vain testipyynnöt.

Tuotannon hyötykuorman ymmärtäminen

Tuotannon tilitapahtumat käyttävät yhteistä JSON-kirjekuorta:

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

Ylimmän tason ominaisuudet tarkoittavat seuraavaa:

• id — Tapahtumatunnus. Vastaa X-Maildroppa-Event-Id-otsikkoa.
• type — Päätepisteen muokkaimessa valittu tapahtuma-avain.
• schema_version — Hyötykuorman skeeman versio. Käytä sitä päättäessäsi, miten tapahtuma jäsennetään.
• created_at — Hyötykuorman luontiaika UTC-aikana.
• livemode — true tuotantotapahtumille ja false testitapahtumille.
• data — Tapahtumakohtainen sisältö.

Reititä tapahtumat täsmällisen type-arvon perusteella. Ohita ylimääräiset ominaisuudet, joita integraatiosi ei tarvitse, jotta yhteensopivat hyötykuorman lisäykset eivät riko vastaanotinta.

Tilaajatapahtuman hyötykuorma

Tilaajatapahtumat sisältävät nykyisen tilaajaesityksen kohdassa 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 ja tags ovat taulukoita. Ne voivat olla tyhjiä. Tilaajan ominaisuus voi myös olla null, kun arvoa ei ole, joten vastaanottimen tulee noudattaa hyötykuorman skeemaa eikä olettaa, että jokainen valinnainen profiiliarvo on mukana.

Tunnistetapahtuman hyötykuorma

Tunnistetapahtumat sisältävät sekä tilaajan että tapahtuman aiheuttaneen tunnisteen:

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

Tapahtumassa subscriber.tag_removed data.tag tunnistaa edelleen poistetun tunnisteen, vaikka tilaajan nykyinen tags-taulukko ei enää sisällä sitä.

Tapahtumatunnukset, toimitustunnukset ja idempotenssi

Tapahtumatunnuksella ja toimitustunnuksella on eri tarkoitus.

Tapahtumatunnus

Tapahtumatunnus tunnistaa liiketoimintatapahtuman. Se näkyy seuraavissa:

• Hyötykuorman ylimmän tason id-ominaisuus.
• X-Maildroppa-Event-Id-pyyntöotsikko.
• Toimitushistoria.

Sama tapahtuma voidaan lähettää useisiin tilattuihin päätepisteisiin. Näillä toimituksilla on sama tapahtumatunnus.

Uudelleenyritykset ja manuaaliset toistot säilyttävät myös alkuperäisen tapahtumatunnuksen. Tallenna käsitellyt tapahtumatunnukset ja tee liiketoimintatoiminnosta idempotentti, jotta toistuva pyyntö ei luo päällekkäisiä yhteyshenkilöitä, toista peruuttamatonta toimintoa tai käytä samaa muutosta kahdesti.

Toimitustunnus

Toimitustunnus tunnistaa yhden toimitustietueen. Se näkyy seuraavissa:

• X-Maildroppa-Delivery-Id-pyyntöotsikko.
• Toimitushistoria.

Jokaisella päätepistetoimituksella on oma toimitustunnuksensa. Manuaalinen toisto luo uuden toimitustunnuksen, mutta säilyttää alkuperäisen tapahtumatunnuksen.

Käytä toimitustunnusta tekniseen jäljitykseen ja tukeen. Käytä tapahtumatunnusta liiketoimintatason kaksoiskappaleiden estämiseen.

Oikean HTTP-vastauksen palauttaminen

Maildroppa luokittelee vastaukset seuraavasti:

• Mikä tahansa 2xx-vastaus merkitsee toimituksen onnistuneeksi.
• 408 Request Timeout, 429 Too Many Requests ja 5xx-vastaukset ovat tilapäisiä virheitä, ja niitä voidaan yrittää uudelleen.
• Tilapäiset verkkovirheet yritetään uudelleen.
• Uudelleenohjauksia ja muita 3xx-vastauksia ei seurata, vaan niitä käsitellään lopullisina virheinä.
• Muita 4xx-vastauksia käsitellään lopullisina virheinä, eikä niitä yritetä uudelleen.

Palauta 200, 202 tai 204 vain, kun tapahtuma on hyväksytty turvallisesti. Jos käsittely vie aikaa, tallenna tapahtuma ensin ja palauta onnistumisvastaus ennen hitaamman työn tekemistä asynkronisesti.

Älä palauta uudelleenohjausta toiseen webhook-URL-osoitteeseen. Määritä lopullinen URL-osoite Maildroppassa.

Automaattinen uudelleenyritysaikataulu

Tuotantotoimituksille voidaan tehdä enintään seitsemän HTTP-yritystä.

Uudelleenyrityskelpoisen virheen jälkeen Maildroppa ajoittaa seuraavan yrityksen näillä viiveillä:

1. Yrityksen 1 jälkeen: 1 minuutti
2. Yrityksen 2 jälkeen: 5 minuuttia
3. Yrityksen 3 jälkeen: 30 minuuttia
4. Yrityksen 4 jälkeen: 2 tuntia
5. Yrityksen 5 jälkeen: 12 tuntia
6. Yrityksen 6 jälkeen: 24 tuntia

Jos yritys 7 saa edelleen uudelleenyrityskelpoisen virheen, toimituksesta tulee Dead eikä uusia automaattisia yrityksiä ajoiteta.

Aikataulu mitataan yksittäisistä epäonnistuneista yrityksistä. Todellinen toimitusaika voi olla hieman myöhemmin, koska toimitukset käsitellään asynkronisesti ja niihin sovelletaan myös järjestelmän suojausrajoituksia.

Korjaa vastaanottimen tilapäinen ongelma ennen näytettyä “Next retry” -aikaa aina kun mahdollista. Jos automaattiset yritykset ovat päättyneet, käytä Replay-toimintoa, kun vastaanotin toimii taas.

Toimitushistorian ymmärtäminen

Toimitushistoria kuuluu sillä hetkellä valitulle päätepisteelle. Päätepisteen URL-osoite näkyy osion otsikossa, jotta voit varmistaa, minkä päätepisteen historiaa tarkastelet.

Käytä seuraavia suodattimia:

• All — Näyttää tuotanto- ja testitoimitukset.
• Production — Näyttää vain reaaliaikaisten tapahtumien toimitukset.
• Test — Näyttää vain manuaaliset testit.

Napsauta “Refresh” hakeaksesi uusimman tilan. Historiaa ei tarvitse pitää avoinna, kun Maildroppa lähettää toimitusta tai yrittää sitä uudelleen.

Sivulla näytetään valitun suodattimen 50 uusinta vastaavaa toimitusta.

Toimituksen sarakkeet

Jokainen rivi sisältää:

• Created — Milloin toimitustietue luotiin.
• State — Pending, Success, Failed tai Dead.
• HTTP — Vastausstatus, yritysten määrä ja kesto sekä seuraavan uudelleenyrityksen aika tarvittaessa.
• Subscriber — Tilaajan sähköpostiosoite, kun tapahtuma liittyy tilaajaan.
• Delivery — Tapahtumatyyppi, tapahtumatunnus ja toimitustunnus.
• Actions — Replay, kun toimitus voidaan toistaa.

Jos HTTP-pyyntöä ei tehty, HTTP-sarakkeessa näkyy “No HTTP attempt”. Näin voi tapahtua, kun Maildroppa hylkää pyynnön ennen lähettämistä, esimerkiksi jos allekirjoitussalaisuus puuttuu tai tallennettua kohdetta ei enää voida käyttää turvallisesti.

Kun saatavilla, rivillä näkyvät myös vastaanottimen palauttama virhe ja vastausote. Älä palauta webhook-vastauksen rungossa salaisuuksia tai arkaluonteisia henkilötietoja, sillä osa vastauksesta voi näkyä tilin toimituslokissa.

Toimituksen tilat

Pending tarkoittaa, että toimitus odottaa ensimmäistä yritystä tai ajoitettua uudelleenyritystä. “Next retry” näkyy, kun seuraava yritys on ajoitettu.

Success tarkoittaa, että vastaanotin palautti 2xx-vastauksen. Uusia automaattisia yrityksiä ei tarvita.

Failed tarkoittaa, että toimitus päättyi ei-uudelleenyrityskelpoiseen ongelmaan, hylättiin ennen HTTP-yritystä tai pysäytettiin ennen lähettämistä.

Dead tarkoittaa, että kaikki automaattiset yritykset käytettiin uudelleenyrityskelpoiseen ongelmaan ilman onnistunutta vastausta.

Historian säilytys

Toimitustietueita säilytetään rajoitetun ajan:

• Onnistuneet tuotantotoimitukset: 30 päivää
• Epäonnistuneet tuotantotoimitukset: 90 päivää
• Dead-tuotantotoimitukset: 90 päivää
• Testitoimitukset: 30 päivää

Pidä omat integraatiolokisi, jos tarvitset pidemmän tarkastushistorian. Tallenna tapahtumatunnukset ja toimitustunnukset, mutta vältä salaisuuksien tarpeetonta tallentamista.

Toimituksen toistaminen

Napsauta “Replay”, kun valmis tuotantotoimitus halutaan yrittää uudelleen.

Replay on käytettävissä tuotantotoimituksille, joiden tila on Success, Failed tai Dead. Se ei ole käytettävissä Pending-tilassa, eikä testitoimituksia voi toistaa.

Toisto:

• Luo uuden Pending-tilassa olevan toimituksen.
• Luo uuden toimitustunnuksen.
• Säilyttää alkuperäisen tapahtumatunnuksen.
• Säilyttää alkuperäisen tapahtumatyypin ja JSON-hyötykuorman.
• Käyttää alkuperäistä tallennettua kohde-URL-osoitetta ja mukautettujen otsikoiden tilannekuvaa.
• Käyttää nykyistä allekirjoitussalaisuutta, kun uusi pyyntö luodaan.

Toisto ei rakenna hyötykuormaa uudelleen tilaajan nykyisistä tiedoista. Se lähettää alkuperäisen tapahtuman tilannekuvan uudelleen. Tämä tekee toistosta tarkastettavan ja estää historiallista tapahtumaa muuttamasta merkitystään huomaamatta.

Samasta lähdetoimituksesta voi olla kerrallaan Pending-tilassa vain yksi toisto. Odota, että kyseinen toisto päättyy, ennen kuin pyydät uutta.

Varmista, että päätepiste on aktiivinen ennen toistoa. Jos päätepiste on passiivinen, jonossa olevaa toistoa ei voida toimittaa onnistuneesti.

Koska vastaanotin on voinut suorittaa liiketoimintatoiminnon, vaikka Maildroppa ei saanut onnistumisvastausta, toisto voi tuottaa päällekkäisen pyynnön. Tapahtumatunnuksen kaksoiskappaleiden tunnistus suojaa yhdistettyä järjestelmää toiminnon toistamiselta.

Päätepisteen muokkaaminen

Napsauta “Edit” muuttaaksesi URL-osoitetta, tapahtumavalintaa, mukautettuja otsikoita tai aktiivista tilaa.

Ennen tallentamista:

1. Varmista, että uusi URL-osoite on jo käytettävissä.
2. Jätä tallennettujen otsikoiden arvot tyhjiksi, jos niiden tulee säilyä ennallaan.
3. Syötä uusi arvo jokaiselle uudelleennimetylle otsikolle.
4. Tarkista tapahtumavalinta, jotta tarvittavia ilmoituksia ei poisteta vahingossa.
5. Tallenna ja lähetä uusi Test webhook.

Muista, että jonossa olevat toimitukset säilyttävät nykyisen URL-osoitteensa ja mukautettujen otsikoiden tilannekuvansa. Testaa uusi määritys tulevia toimituksia varten sen sijaan, että olettaisit sen muuttavan vanhaa jonossa olevaa pyyntöä.

Päätepisteen deaktivointi

Käytä On/Off-kytkintä, kun haluat keskeyttää integraation poistamatta sen määritystä ja historiaa.

Kun päätepiste kytketään pois päältä:

• Uusia tapahtumia ei enää lisätä sen jonoon.
• Pending-toimitukset, joita ei ole vielä varattu lähetystä varten, merkitään Failed-tilaan.
• Test-toiminto poistetaan käytöstä.
• Päätepiste on edelleen muokattavissa ja myöhemmin aktivoitavissa.

Pyyntö, joka on jo käynnissä deaktivointihetkellä, voi silti valmistua. Tarkista toimitushistoria päätepisteen poiskytkemisen jälkeen, jos tällä erolla on integraatiosi kannalta merkitystä.

Päätepisteen ollessa passiivinen väliin jääneitä tapahtumia ei täydennetä, kun otat sen uudelleen käyttöön.

Päätepisteen poistaminen

Napsauta “Delete” ja vahvista varoitus, kun päätepistettä ei enää tarvita.

Poistaminen poistaa päätepisteen sivulta, pysäyttää tulevat tapahtumatoimitukset ja merkitsee lähettämistä varten vielä varaamattomat odottavat toimitukset epäonnistuneiksi.

Delete ei ole väliaikainen keskeytystoiminto. Käytä On/Off-kytkintä, kun saatat tarvita määrityksen tai sen näkyvän historian myöhemmin uudelleen.

Kirjaa ennen poistamista kaikki tapahtumatunnukset tai toimitustunnukset, joita vielä tarvitset integraatiosi tarkastuksessa.

Vianmääritys

Päätepistettä ei voi tallentaa

Tarkista, että:

• URL-osoite alkaa merkkijonolla https://.
• URL-osoite käyttää julkista isäntänimeä ja porttia 443.
• URL-osoite ei sisällä muuttujia, kirjautumistietoja tai fragmenttia.
• Vähintään yksi tapahtuma on valittu.
• Jokaisella mukautetulla otsikolla on yksilöllinen nimi ja arvo.
• Varattuja Maildroppa- ja HTTP-otsikoita ei käytetä mukautettuina niminä.

Test on poissa käytöstä

Test on käytettävissä vain aktiiviselle päätepisteelle. Kytke päätepiste päälle tai muokkaa sitä ja valitse “Active”, tallenna ja testaa vasta sitten.

Test ei näytä HTTP-yritystä

Luo allekirjoitussalaisuus, jos tila on Missing. Tarkista myös, onko kohteen isäntänimi julkinen ja ohjautuuko se edelleen oikein.

Pyyntö voidaan hylätä ennen lähettämistä, jos sen salaisuus, URL-osoite, mukautetut otsikot tai kohteen turvallisuustarkistus on virheellinen.

Vastaanotin palauttaa 401- tai 403-vastauksen

Tarkista tallennettu mukautetun otsikon nimi ja tunnistetieto. Muokkaa päätepistettä ja syötä arvo uudelleen, jos se on muuttunut.

Varmista myös, ettei vastaanotin sekoita omaa API-tunnistetietoaan Maildroppa-allekirjoitukseen. Mukautettu Authorization-otsikko ja X-Maildroppa-Signature palvelevat eri tarkoituksia, ja ne voidaan tarkistaa erikseen.

Vastaanotin palauttaa uudelleenohjauksen

Maildroppa ei seuraa uudelleenohjauksia. Korvaa päätepisteen URL-osoite lopullisella julkisella HTTPS-URL-osoitteella ja testaa uudelleen.

Allekirjoitus ei täsmää

Varmista, että vastaanotin:

• Käyttää nykyistä allekirjoitussalaisuutta.
• Käyttää täsmällistä X-Maildroppa-Timestamp-arvoa.
• Allekirjoittaa merkkijonon <timestamp>.<raw request body>.
• Käyttää HMAC-SHA256:ta ja pienaakkosina esitettyä heksadesimaalitulosta.
• Vertaa koko arvoa, mukaan lukien v1=.
• Tekee vertailun ennen kuin JSON-jäsennys muuttaa runkoa.

Sama tapahtuma saapuu useammin kuin kerran

Näin voi tapahtua verkkokatkoksen, uudelleenyrityksen tai manuaalisen toiston jälkeen. Webhook-toimitusjärjestelmille on normaalia tarjota vähintään kerran toimitus eikä täsmälleen kerran toimitusta.

Käytä tapahtumatunnusta idempotenssiavaimena. Palauta 2xx-vastaus, kun jo käsitelty tapahtumatunnus vastaanotetaan uudelleen eikä lisätoimia tarvita.

Toimitus on Pending-tilassa

Katso HTTP-sarakkeen “Next retry” -kohta. Uudelleenyrityskelpoinen 408, 429, 5xx tai tilapäinen verkkovirhe pitää toimituksen Pending-tilassa seuraavaan ajoitettuun yritykseen asti.

Napsauta “Refresh” uudelleenyrityksen jälkeen ladataksesi uusimman tilan.

Toimitus on Dead-tilassa

Kaikki automaattiset yritykset on käytetty. Korjaa vastaanotin ensin, varmista, että päätepiste on aktiivinen, lähetä Test webhook ja käytä sitten tuotantotoimituksen Replay-toimintoa.

Suositeltu tuotannon tarkistuslista

Varmista ennen päätepisteeseen luottamista tuotannossa, että kaikki seuraavat kohdat täyttyvät:

1. Vastaanotin käyttää vakaata julkista HTTPS-URL-osoitetta, jolla on kelvollinen sertifikaatti.
2. Allekirjoitussalaisuus on tallennettu lähdekoodin ulkopuolelle.
3. Allekirjoitus tarkistetaan muuttamattomasta raakasisällöstä.
4. Vanhat aikaleimat hylätään dokumentoidun toleranssin mukaisesti.
5. Vastaanotin tallentaa tapahtumatunnukset ja estää niiden kaksoiskäsittelyn.
6. Vastaanotin kirjaa tapahtumatunnukset ja toimitustunnukset jäljitystä varten.
7. Hidas käsittely tapahtuu sen jälkeen, kun tapahtuma on hyväksytty pysyvästi.
8. 2xx-vastaus palautetaan vain hyväksytyistä tapahtumista.
9. Mukautetut tunnistetiedot tallennetaan otsikoihin, ei URL-osoitteeseen.
10. Vain tarvittavat tapahtumatyypit on valittu.
11. Test webhook onnistuu ja näkyy oikein toimitushistoriassa.
12. Valvonta ilmoittaa, kun tuotantotoimitukset alkavat palauttaa virheitä.

Kun nämä suojatoimet ovat käytössä, Webhooks-sivu tarjoaa luotettavan integraation molemmat puolet: turvallisen tapahtumatoimituksen sovellukseesi ja selkeän operatiivisen historian Maildroppassa.