Abonnements- og betalingshændelser via webhooks

Historisk tilbageblik: november 2025 til august 2026; ændret siden februar til august 2026

Denne artikel er skrevet efterfølgende og beskriver funktionen, som den blev udbygget i den angivne periode. Webhook-hændelserne blev udvidet fra abonnementets grundlæggende livscyklus til blandt andet genoptagelse, betalingsfejl og betalingsresultater. Se vejledningen til offentlig API og webhooks (Markdown-fil, AI-agentvenlig) for den aktuelle hændelsesliste og kontrakt.

Webhooks giver et eksternt system besked, når Alunta registrerer en ændring. De er nyttige, hvis en kundeportal, et CRM-system eller et økonomisystem skal følge abonnementer uden at spørge Alunta hele tiden. Hændelsen er et signal om Aluntas tilstand; den bekræfter ikke, at dit eget system allerede har udført sin opfølgende handling.

De vigtigste hændelser

Livscyklussen kan blandt andet beskrives med subscription.started, subscription.ended og subscription.resumed. En opsigelse og en afslutning er forskellige: opsigelsen kan planlægge eller markere, at aftalen skal stoppe, mens afslutningen fortæller, at abonnementet faktisk er afsluttet. Senere blev subscription.payment_succeeded og subscription.payment_failed føjet til, så et integreret system kan reagere på hvert betalingsudfald. payment_succeeded bekræfter den konkrete betaling, men en delbetaling eller ratebetaling kan stadig efterlade fakturaen med saldo. En invoice.paid-hændelse handler om fakturaens betalingsstatus og bør ikke forveksles med, at et abonnement nødvendigvis er aktivt.

Brug den dokumenterede eventtype og den deduplikeringsnøgle, som netop den eventtype giver, til at vælge handling. subscription.started, subscription.ended, subscription.payment_succeeded og invoice.paid har en stabil data.event_id, som kan bruges ved retries og replay. subscription.payment_failed kan komme flere gange for separate retry-forsøg og har ikke en stabil event_id; behold derfor hver levering og brug den dokumenterede webhook_uuid, hvor den findes, som leveringsnøgle. Slå kun de eventtyper til, som integrationen behøver, og læs altid den aktuelle offentlige API-reference for felter og statusværdier.

Sådan kommer du i gang

1. Aktivér API-/webhook-funktionen for teamet, og opret en HTTPS-modtager.
2. Registrér endpointet og vælg de nødvendige abonnement- og betalingshændelser.
3. Kontrollér signaturen på den rå request-krop, før payloaden behandles.
4. Gem den nøgle, som den konkrete eventtype dokumenterer, og behandl den idempotent. Brug data.event_id for eventtyper, der har en stabil nøgle, og behold separate subscription.payment_failed-forsøg; brug webhook_uuid, hvor den findes, som leveringsidentitet. En gentaget levering skal give samme slutresultat som den første uden at slå forskellige betalingsforsøg sammen.
5. Returnér hurtigt en succesfuld HTTP-status, og udfør den længere behandling bagefter.

Når abonnementet starter, stopper, genoptages eller får et betalingsudfald, kan systemet bruge den relevante stabile nøgle og payloadens relationer til abonnement og faktura til at opdatere sin lokale visning. Brug eventtypen sammen med payloadens relationer; rækkefølgen af leveringer bør ikke alene bruges som forretningsregel.

Typiske spørgsmål

Hvorfor kommer samme event igen? Levering kan gentages efter fejl eller timeout. Deduplikér data.event_id, når den konkrete eventtype dokumenterer den, eller brug webhook_uuid som leveringsidentitet, hvor den findes. Behold separate betalingsfejlforsøg, selv om de vedrører samme abonnement.

Er payment_failed det samme som en opsigelse? Nej. Det er et betalingsresultat. Den aktuelle abonnementsstatus skal læses separat.

Hvad sker der, hvis modtageren var nede? Se leveringsloggen, ret modtageren og gentag den fejlede levering, når integrationen er klar.

Se vejledningen til offentlig API og webhooks (Markdown-fil, AI-agentvenlig) for den nutidige arbejdsgang.

Vælg hændelse efter forretningsbehov

Et kundeportalssystem kan lytte på subscription.started for at vise adgang, på subscription.ended for at lukke en aftale, og på subscription.resumed for at åbne den igen. Et økonomisystem kan lytte på invoice.paid for at markere et krav som betalt. Et support- eller betalingssystem kan bruge subscription.payment_succeeded og subscription.payment_failed til at vise betalingsresultater. Hændelserne bør ikke blandes sammen: en delbetaling er ikke nødvendigvis en betalt faktura, og en betalingsfejl er ikke i sig selv en opsigelse.

Gem en lokal modtagelsespost med eventtype, den relevante nøgle og modtagelsestidspunkt. Først når signaturen er godkendt, må systemet udføre sin handling. Hvis samme stabile event_id kommer igen, returnerer modtageren stadig en succesfuld status, men springer den allerede gennemførte forretningshandling over. For betalingsfejl skal separate leveringer ikke slås sammen alene på abonnementets UUID. Hvis events kommer i en anden rækkefølge end forventet, hentes den aktuelle subscription eller invoice, før lokal status ændres.

Hvorfor kommer der ikke en hændelse? Kontrollér endpoint, valgt eventtype, teamets API-adgang og leveringsloggen. En funktion i produktet er ikke automatisk en webhook, før eventtypen findes i den offentlige kontrakt.

Kan en webhook udløse en handling? Ja, i dit system, men gør handlingen idempotent og vis tydeligt, hvilken Alunta-status den bygger på.