Webhooks voor abonnementen

Verkoop je software of een dienst die je zelf aan- en uitzet, dan kan je eigen systeem elke wijziging van een abonnement volgen. Qontivo stuurt dan bij elke wijziging een bericht naar een adres van jou.

Zo werkt het

1. Ga naar Instellingen, Integraties, en open de kaart Webhooks voor abonnementen (Abonnementen moet aanstaan bij Instellingen, Facturering).
2. Vul het adres in (https) en klik op Webhook toevoegen. Je ziet één keer het geheim om de handtekening te controleren. Bewaar het in je eigen systeem.
3. Bij elke wijziging stuurt Qontivo een POST met JSON naar dat adres. Antwoordt je systeem niet met een 2xx-code, dan probeert Qontivo het nog vier keer: na 1 minuut, 5 minuten, een half uur en 2 uur.

De gebeurtenissen

• subscription.started: gestart, na de eerste betaling of bij de start van een proef.
• subscription.status_changed: de status veranderde (trial, active, past_due, suspended, ended), met previous_status.
• subscription.access_changed: wat het abonnement nog geeft (full, read_only, locked), met previous_access.
• subscription.updated: gepauzeerd, hervat, opgezegd of gewisseld.
• subscription.payment_failed: een automatische afschrijving is mislukt.

De inhoud bevat event, occurred_at en subscription met onder meer id, status, access, plan, period_start, next_billing_on, cancel_effective_on, limits en customer (naam en e-mailadres).

De handtekening controleren

De kop Qontivo-Signature ziet eruit als t=1760430000,v1=5f2b…. Bereken een HMAC-SHA256 van de tekst t, een punt en de body zoals je hem ontving, met je geheim als sleutel. Komt die uit op v1, dan komt het bericht van Qontivo. Weiger berichten met een t die meer dan vijf minuten oud is.

Goed om te weten

• Het geheim staat versleuteld in Qontivo en is na het toevoegen niet meer te zien. Kwijt? Verwijder de webhook en voeg hem opnieuw toe.
• Bij elke webhook zie je wanneer hij het laatst iets stuurde en of dat lukte.