Prenumerations- och betalningshändelser via webhooks

Historisk tillbakablick: november 2025 till augusti 2026; ändrat sedan februari–augusti 2026

Den här artikeln skrevs i efterhand och beskriver hur funktionen utökades under den angivna perioden. Webhook-händelserna växte från den grundläggande prenumerationslivscykeln till att även omfatta återupptagning, betalningsfel och betalningsresultat. Se guiden om publikt API och webhooks (Markdown-fil, AI-agentvenlig) för aktuell händelselista och kontrakt.

Webhooks meddelar ett externt system när Alunta registrerar en ändring. De är användbara när en kundportal, ett CRM-system eller ett bokföringssystem behöver följa prenumerationer utan att kontinuerligt söka av Alunta. En händelse signalerar Aluntas tillstånd; den bekräftar inte att ditt eget system har slutfört sin uppföljningsåtgärd.

De viktigaste händelserna

Livscykeln kan omfatta subscription.started, subscription.ended och subscription.resumed. Uppsägning och avslut är olika saker: en uppsägning kan schemalägga eller markera att ett avtal ska upphöra, medan avslut betyder att prenumerationen faktiskt har upphört. Senare lades subscription.payment_succeeded och subscription.payment_failed till, så att en integration kan reagera på varje betalningsresultat. payment_succeeded bekräftar själva betalningen, men en delbetalning eller avbetalning kan lämna ett saldo på fakturan. En invoice.paid-händelse beskriver fakturans betalningsstatus och ska inte behandlas som bevis på att en prenumeration är aktiv.

Använd den dokumenterade händelsetypen och dedupliceringsnyckeln som anges för den typen. subscription.started, subscription.ended, subscription.payment_succeeded och invoice.paid har ett stabilt data.event_id för nya försök och uppspelningar. subscription.payment_failed kan komma flera gånger för separata nya betalningsförsök och har inget stabilt event_id; behåll varje leverans och använd dokumenterat webhook_uuid som leveransnyckel när det finns. Prenumerera endast på händelser som integrationen behöver och använd alltid den aktuella publika API-referensen för fält och statusvärden.

Kom igång

1. Aktivera API-/webhook-funktionen för teamet och skapa en HTTPS-mottagare.
2. Registrera ändpunkten och välj de prenumerations- och betalningshändelser som behövs.
3. Verifiera signaturen mot den råa förfrågningskroppen innan nyttolasten behandlas.
4. Spara nyckeln som dokumenterats för den specifika händelsetypen och behandla den idempotent. Använd data.event_id för händelsetyper som har en stabil nyckel, behåll separata subscription.payment_failed-försök och använd webhook_uuid som leveransidentitet när den finns. En upprepad leverans ska ge samma slutliga tillstånd som den första utan att separata betalningsförsök slås ihop.
5. Returnera snabbt en lyckad HTTP-status och utför sedan tidskrävande behandling.

När en prenumeration startar, avslutas, återupptas eller får ett betalningsfel använder du den relevanta stabila nyckeln och nyttolastens prenumerations- och fakturarelationer för att uppdatera den lokala vyn. Använd händelsetypen tillsammans med relationerna; använd inte enbart leveransordningen som affärsregel.

Vanliga frågor

Varför kom samma händelse igen? Leveranser kan upprepas efter ett fel eller en tidsgräns. Deduplicera med data.event_id när den specifika händelsetypen dokumenterar det, eller använd webhook_uuid som leveransidentitet när det finns. Behåll separata betalningsfelsförsök även om de gäller samma prenumeration.

Är payment_failed samma sak som uppsägning? Nej. Det är ett betalningsresultat. Läs prenumerationens aktuella status separat.

Vad händer om mottagaren inte var tillgänglig? Öppna leveransloggen, rätta mottagaren och spela upp den misslyckade leveransen igen när integrationen är redo.

Se guiden om publikt API och webhooks (Markdown-fil, AI-agentvenlig) för det aktuella flödet.

Välj händelse efter verksamhetsbehov

En kundportal kan lyssna efter subscription.started för att ge åtkomst, subscription.ended för att avsluta ett avtal och subscription.resumed för att öppna det igen. Ett bokföringssystem kan lyssna efter invoice.paid för att markera en fordran som betald. Ett support- eller betalningssystem kan använda subscription.payment_succeeded och subscription.payment_failed för att visa betalningsresultat. Blanda inte ihop händelserna: en delbetalning betyder inte nödvändigtvis att fakturan är betald, och ett betalningsfel är inte i sig en uppsägning.

Spara ett lokalt kvitto med händelsetyp, relevant nyckel och mottagningstid. Utför affärsåtgärden först efter signaturverifiering. Om samma stabila event_id kommer igen svarar mottagaren fortfarande med en lyckad status men hoppar över den redan slutförda åtgärden. Slå inte ihop separata leveranser för betalningsfel bara för att de delar ett prenumerations-UUID. Om händelser kommer i oväntad ordning hämtar du prenumerationens eller fakturans aktuella status innan du ändrar lokal status.

Varför kom ingen händelse? Kontrollera ändpunkten, vald händelse, teamets API-åtkomst och leveransloggen. En produktfunktion blir inte automatiskt en webhook förrän händelsen finns i det publika kontraktet.

Kan en webhook utlösa en åtgärd? Ja, i ditt system, men gör åtgärden idempotent och visa vilken Alunta-status den bygger på.