Webhookit & tuplarivit: retry, idempotency ja tuplalaskujen esto

TL;DR – Tiivistelmä

Webhookit lähetetään usein uudelleen (retry), mikä aiheuttaa tuplatilauksia ja -laskuja. Ratkaisu: idempotency key tai dedup-taulu. Tarkista webhook-ID ennen käsittelyä.

Miksi tuplia syntyy

Webhook-integraatiot toimivat "push"-periaatteella: lähettäjä kutsuu sinun endpointiasi. Ongelma syntyy kun:

Verkkokatko: Lähettäjä ei saa vastausta → lähettää uudelleen
Timeout: Käsittely kestää liian kauan → lähettäjä olettaa epäonnistumisen
Virhe käsittelyssä: Lähettäjä lähettää uudelleen kunnes onnistuu
Käyttäjän toiminta: Käyttäjä klikkaa "Lähetä" kahdesti

Lähettäjä tekee oikein – varmistaa että viesti menee perille. Sinun tehtäväsi on käsitellä duplikaatit.

Retry-strategiat

Lähettäjän puolella (ei sinun hallinnassasi)

Immediate retry: Heti uudelleen (1–3 kertaa)
Exponential backoff: 1s, 2s, 4s, 8s... kasvava viive
Dead letter queue: Epäonnistuneet siirretään jonoon myöhempää käsittelyä varten

Vastaanottajan puolella (sinä)

Vastaa 200 heti: Kuittaa vastaanotto ennen käsittelyä (asynkroninen)
Nopea käsittely: Alle 5 sekuntia tai siirrä taustajobiin
Idempotency: Käsittele sama viesti vain kerran

Idempotency käytännössä

Idempotency = sama operaatio tuottaa saman tuloksen, vaikka suoritetaan monta kertaa.

Idempotency key

Lähettäjä antaa uniikin ID:n (esim. X-Idempotency-Key header tai event_id bodyssa).

            1. Vastaanota webhook

            2. Tarkista: onko event_id jo käsitelty?

            3. Jos kyllä → palauta 200, älä tee mitään

            4. Jos ei → käsittele ja tallenna event_id

Dedup-taulu

Tallenna käsitellyt webhook-ID:t tietokantaan:

            CREATE TABLE processed_webhooks (

              event_id VARCHAR(255) PRIMARY KEY,

              processed_at TIMESTAMP DEFAULT NOW()

            );

Tapaus: tilaus → lasku → varasto

Verkkokaupassa syntyy tilaus → pitää luoda lasku ja vähentää varastosta.

Missä kohtaa dedup tehdään?

Vaihtoehto 1: Heti ensimmäisessä vaiheessa (suositus)
Vaihtoehto 2: Jokaisessa vaiheessa erikseen (turvallisempi mutta monimutkaisempi)

Suositus: Tarkista tilaus-ID heti webhook-endpointissa. Jos jo käsitelty → 200 OK, ei toimenpiteitä.

Onko teillä tuplalaskuja/tuplatilauksia?

Lähetä tapahtumaketju → annan korjausmallin.

Kysy korjausta

Checklist: miten tunnistat ja estät tuplat

☐ Tarkista webhook-dokumentaatio: Onko retry-logiikka? Mikä on uniikki ID?
☐ Tallenna käsitellyt ID:t: Dedup-taulu tai cache (Redis)
☐ Tarkista ennen käsittelyä: Onko ID jo käsitelty?
☐ Vastaa nopeasti: 200 OK heti, käsittely taustalla
☐ Monitoroi: Hälytys jos samaa ID:tä tulee monta kertaa
☐ Testaa: Simuloi retry-tilanteet

Lue myös

Kenelle tämä sopii?

Kehittäjät, jotka rakentavat webhook-integraatioita
Yritykset, joilla on tuplatilaus- tai tuplalaskuongelmia
IT-vastaavat, jotka debugaavat integraatio-ongelmia

Tyypillinen toimitus Datastormilla

Analyysi: Missä kohtaa tuplat syntyvät
Korjaus: Idempotency-logiikka, dedup-taulu
Testaus: Retry-simulointi, monitorointi

Pyydä arvio