Stripe-tapahtuman käsittely

Yhteenveto

• Laukaisin: POST /api/v1/billing/stripe/webhook (deployment/template.yaml:810) → oma lambda StripeWebhookFunction, handler stripe_webhook/handler.handler
• Lopputulos: tenantti on provisioitu tai sen tilaustila ja tuoteoikeudet ovat päivittyneet. Epäonnistuessa kuorma on DLQ-jonossa ja Stripe uusii.
• Idempotentti: kyllä, mutta vain valmistuneille tapahtumille. Tapahtumalukko torjuu uusinnat vasta, kun ensimmäinen käsittely on merkitty valmiiksi — ks. Stripe-tapahtumalukko.

Tämä on ainoa moduulin sisääntulopiste, joka ei tule VeraFramen omasta käyttöliittymästä. Käsittelijä on tarkoituksella ohut: se tunnistaa tenantin ja delegoi säännöt saas_onboarding.py:lle, jotta sama logiikka toimii myös skripteistä ja kirjautumisesta.

Sekvenssi

sequenceDiagram
    participant Stripe
    participant WH as stripe_webhook.handler
    participant Lock as StripeWebhookEventTable
    participant Onb as saas_onboarding
    participant Store as CONFIG_BUCKET
    participant DLQ as SQS DLQ

    Stripe->>WH: POST /api/v1/billing/stripe/webhook
    WH->>WH: verify_stripe_signature (HMAC, v1)
    WH->>Lock: _try_claim_event (ehdollinen put_item)
    Lock-->>WH: claimed | processed
    alt jo käsitelty
        WH-->>Stripe: 200 { duplicate: true }
    else
        WH->>WH: tapahtumatyypin haarautus
        WH->>Onb: provision_saas_tenant / update_saas_subscription
        Onb->>Store: config.json (koko dokumentti)
        WH->>Lock: _mark_event_processed
        WH-->>Stripe: 200 { received: true }
    end
    Note over WH,DLQ: poikkeus → _release_event_claim + _send_to_dlq → 500

Vaiheet

Vaihe 1 — Allekirjoituksen tarkistus

• Mitä: Stripe-Signature-otsikko jäsennetään (t= aikaleima, v1= allekirjoitukset) ja verrataan HMAC-SHA256-arvoon salaisuudella STRIPE_WEBHOOK_SECRET. Vertailu on vakioaikainen (hmac.compare_digest), ja mikä tahansa v1-arvo riittää.
• Koodi: stripe_webhook/handler.py:45, tarkistin saas_onboarding.py:905 (verify_stripe_signature)
• Data sisään: raaka body-merkkijono (jäsentämätön, koska allekirjoitus lasketaan siitä sellaisenaan) → 400 tai jäsennetty JSON
• Huom: aikaleimaa t ei verrata nykyhetkeen. Replay-suojaa ei siis ole allekirjoitustasolla — sen hoitaa tapahtumalukko (vaihe 2), mutta vain 30 vrk TTL:n ajan.

Vaihe 2 — Idempotenssivaraus

• Mitä: stripe#{event_id}-rivi varataan ehdollisella kirjoituksella. Jos rivi on jo tilassa processed, palautetaan heti 200 {duplicate: true} käsittelemättä mitään.
• Koodi: stripe_webhook/handler.py:57, stripe_webhook/handler.py:190 (_try_claim_event)
• Data: Stripe-tapahtumalukko
• Huom: jos id puuttuu kuormasta, koko lukko ohitetaan (if event_id:). Sama koskee tilannetta, jossa taulun nimi puuttuu ympäristöstä.

Vaihe 3 — Tenantin tunnistus

• Mitä: ensisijainen lähde on tapahtuman metadatan customer_id. Jos se puuttuu, tenantti etsitään Stripen customer-tunnuksella selaamalla koko konfiguraatiosäiliö läpi ja vertaamalla saas.stripe_customer_id-kenttää.
• Koodi: stripe_webhook/handler.py:137 (_resolve_customer_id), saas_onboarding.py:676 (find_customer_config_by_stripe_customer_id)
• Data: Tenantin saas-lohko (ei näytteessä)
• Miksi varapolku: Stripe-portaalissa tehdyt muutokset ja uudelleenaktivoinnit eivät aina kanna alkuperäistä metadataa.
• Huom: varapolku on list_objects(bucket, "") eli täysi listaus ja get_object jokaiselle */config.json-avaimelle. Kustannus kasvaa lineaarisesti tenanttien määrässä ja se maksetaan joka kerta, kun metadata puuttuu.

Vaihe 4 — Tapahtumatyypin haarautus

• Mitä: viisi tunnettua tapahtumaa; tuntematon tyyppi kuitataan 200:lla ilman toimenpiteitä.
• Koodi: stripe_webhook/handler.py:63–124
• Data ulos: Tenantin saas-lohko (ei näytteessä) + Tuoteominaisuudet ja compliance (ei näytteessä)

Kaksi yksityiskohtaa, jotka kannattaa tietää:

• checkout.session.completed ei tarkista tenanttitunnuksen olemassaoloa. Jos metadatasta puuttuu customer_id ja company_name, suggest_customer_id normalisoi tyhjän merkkijonon muotoon tenant (saas_onboarding.py:55) ja provisioi tenantin nimeltä tenant. Muissa haaroissa tyhjä tunnus johtaa toimettomuuteen (if customer_id:), mutta tässä haarassa ei ole vastaavaa vartijaa.
• invoice.payment_failed sulkee hallintapaneelin. past_due osuu update_saas_subscriptionin kolmanteen haaraan, joka nollaa myös admin_dashboard- ja export_reports-liput. Maksun epäonnistuminen estää siis asiakkaalta myös laskutusportaaliin pääsyn, koska /saas/billing-portal on admin-reitti (handler_api.py:427, handler_api.py:447).

Vaihe 5 — Valmistuminen tai DLQ

• Mitä: onnistuessa rivi merkitään processed-tilaan ja palautetaan 200 {received, type}. Poikkeus vapauttaa varauksen, kirjoittaa kuorman DLQ-jonoon ja palauttaa 500 sanitoidulla virheviestillä (Stripen kuorman sisältöä ei kaiuteta ulos).
• Koodi: stripe_webhook/handler.py:125, stripe_webhook/handler.py:220 (_mark_event_processed), stripe_webhook/handler.py:236 (_release_event_claim), stripe_webhook/handler.py:246 (_send_to_dlq)
• Data: DLQ-viesti {event_type, payload, error[:1000], captured_at} jonoon veraframe-stripe-webhook-dlq-{Environment} (deployment/template.yaml:265, viestin säilytys 14 vrk)
• Valvonta: kaksi CloudWatch-hälytystä — lambdan virheet (deployment/template.yaml:814) ja DLQ:n viestimäärä (deployment/template.yaml:831). Molemmat ilmoittavat SNS-sähköpostiin, jos AlertEmail on annettu.

Virhetilanteet

Hiljainen kuittaus on tässä tarkoituksellinen valinta: tuntematon tyyppi ja löytymätön tenantti saavat 200:n, jotta Stripe ei uusi niitä ikuisesti. Se tarkoittaa myös, ettei tenantin tunnistuksen epäonnistumisesta jää jälkeä mihinkään — ei DLQ:hun eikä hälytykseen.

Liittyvät

• Datavirta: Stripe-tapahtumasta tuoteoikeuksiksi
• Prosessit: Tenantin provisiointi (ei näytteessä) · Tilauksen tilan päivitys (ei näytteessä) · Tilauksen täsmäytys Stripestä
• Liiketoimintaprosessi: Cloud-tilauksen elinkaari