Abonnements- og betalingshendelser via webhooks

Historisk tilbakeblikk: november 2025 til august 2026; endringer fra februar til august 2026

Denne artikkelen ble skrevet i ettertid og beskriver hvordan funksjonen ble utvidet i den angitte perioden. Webhook-hendelsene vokste fra den grunnleggende abonnementslivssyklusen til også å omfatte gjenopptakelse, betalingsfeil og betalingsresultater. Se veiledningen for offentlig API og webhooks (Markdown-fil, AI-agentvenlig) for den gjeldende hendelseslisten og kontrakten.

Webhooks varsler et eksternt system når Alunta registrerer en endring. De er nyttige når en kundeportal, et CRM-system eller et regnskapssystem må følge abonnementer uten å spørre Alunta kontinuerlig. En hendelse signaliserer Aluntas tilstand; den bekrefter ikke at ditt eget system har fullført oppfølgingshandlingen.

De viktigste hendelsene

Livssyklusen kan omfatte subscription.started, subscription.ended og subscription.resumed. Oppsigelse og avslutning er forskjellige ting: En oppsigelse kan planlegge eller markere at en avtale skal stanse, mens avslutning betyr at abonnementet faktisk er avsluttet. Senere ble subscription.payment_succeeded og subscription.payment_failed lagt til, slik at en integrasjon kan reagere på hvert betalingsresultat. payment_succeeded bekrefter selve betalingen, men en delbetaling eller et avdrag kan etterlate en saldo på fakturaen. Hendelsen invoice.paid beskriver fakturaens betalingstilstand og skal ikke behandles som bevis på at et abonnement er aktivt.

Bruk den dokumenterte hendelsestypen og dedupliseringsnøkkelen som gjelder for den typen. subscription.started, subscription.ended, subscription.payment_succeeded og invoice.paid har en stabil data.event_id for forsøk på nytt og avspillinger. subscription.payment_failed kan komme mer enn én gang for separate forsøk på nytt og har ingen stabil event_id; behold hver levering, og bruk den dokumenterte webhook_uuid som leveringsnøkkel når den finnes. Abonner bare på hendelser integrasjonen trenger, og bruk alltid den gjeldende offentlige API-referansen for felt og statusverdier.

Kom i gang

1. Aktiver API-/webhook-funksjonen for teamet, og opprett en HTTPS-mottaker.
2. Registrer endepunktet, og velg de nødvendige abonnements- og betalingshendelsene.
3. Verifiser signaturen mot den opprinnelige forespørselsteksten før du behandler nyttelasten.
4. Lagre nøkkelen som er dokumentert for den bestemte hendelsestypen, og behandle hendelsen idempotent. Bruk data.event_id for hendelsestyper som har en stabil nøkkel, behold separate forsøk for subscription.payment_failed, og bruk webhook_uuid som leveringsidentitet når den finnes. En gjentatt levering skal gi samme sluttresultat som den første uten å slå sammen ulike betalingsforsøk.
5. Returner raskt en vellykket HTTP-status, og utfør deretter eventuell lengre behandling.

Når et abonnement starter, avsluttes eller gjenopptas, eller får en betalingsfeil, bruker du den relevante stabile nøkkelen og nyttelastens koblinger til abonnement og faktura for å oppdatere den lokale visningen. Bruk hendelsestypen sammen med disse koblingene; ikke bruk leveringsrekkefølgen alene som forretningsregel.

Vanlige spørsmål

Hvorfor kom den samme hendelsen igjen? Leveringer kan gjentas etter en feil eller tidsavbrudd. Dedupliser data.event_id når den bestemte hendelsestypen dokumenterer den, eller bruk webhook_uuid som leveringsidentitet når den finnes. Behold separate betalingsfeilforsøk selv når de gjelder samme abonnement.

Er payment_failed det samme som oppsigelse? Nei. Det er et betalingsresultat. Les gjeldende abonnementsstatus separat.

Hva om mottakeren ikke var tilgjengelig? Åpne leveringsloggen, rett mottakeren, og spill av den mislykkede leveringen på nytt når integrasjonen er klar.

Se veiledningen for offentlig API og webhooks (Markdown-fil, AI-agentvenlig) for den gjeldende arbeidsflyten.

Velg hendelse ut fra forretningsbehovet

En kundeportal kan lytte etter subscription.started for å vise tilgang, subscription.ended for å avslutte en avtale og subscription.resumed for å åpne den igjen. Et regnskapssystem kan lytte etter invoice.paid for å markere en fordring som betalt. Et støtte- eller betalingssystem kan bruke subscription.payment_succeeded og subscription.payment_failed for å vise betalingsresultater. Ikke bland sammen hendelsene: En delbetaling betyr ikke nødvendigvis at fakturaen er betalt, og en betalingsfeil er ikke i seg selv en oppsigelse.

Lagre en lokal mottakskvittering med hendelsestype, relevant nøkkel og mottakstidspunkt. Behandle forretningshandlingen først etter at signaturen er verifisert. Hvis den samme stabile event_id kommer igjen, returnerer mottakeren likevel et vellykket svar, men hopper over handlingen som allerede er fullført. Ikke slå sammen separate leveringer av betalingsfeil bare fordi de deler en abonnements-UUID. Hvis hendelsene kommer i uventet rekkefølge, henter du gjeldende abonnements- eller fakturastatus før du endrer lokal status.

Hvorfor kom det ingen hendelse? Kontroller endepunktet, den valgte hendelsen, teamets API-tilgang og leveringsloggen. En produktfunksjon blir ikke automatisk en webhook før hendelsen finnes i den offentlige kontrakten.

Kan en webhook utløse en handling? Ja, i systemet ditt, men gjør handlingen idempotent og vis hvilken Alunta-status den bygger på.