Webhook callbacks

Når hendelser oppstår i Fenerum, sendes en HTTP POST-forespørsel til hvert aktivert endepunkt konfigurert på hver Webhook. Hver forespørsel har et event-felt som identifiserer hendelsestypen og et data-felt som inneholder et øyeblikksbilde av ressursen. Endepunkter bør svare med en hvilken som helst 2XX-status for å bekrefte mottak.

De fleste hendelser er aktivert som standard når en webhook opprettes. Betalingsrelaterte hendelser (payment.authentication_required, payment.declined, card_expires_this_month, payment_card.activated, payment_card.deactivated) er ikke aktivert som standard — aktiver dem eksplisitt via events-feltet på Webhook-ressursen.

Et utvalg av disse hendelsene er også synlig i Swagger console under taggen Webhook callbacks.

account.created

{
  "event": "account.created",
  "data": {
    "uuid": "5c838347-d3ce-40fb-951c-b3190ccf2cba",
    "code": "important_client",
    "company_name": "Important client",
    "legal_address": "Important street 12",
    "legal_zipcode": "1234",
    "legal_city": "Aarhus",
    "legal_country": "DK",
    "legal_vat_number": "DK12345678",
    "billing_same_as_legal": true,
    "billing_address": null,
    "billing_zipcode": null,
    "billing_city": null,
    "billing_country": null,
    "created_date": "2018-11-20T11:25:23.889915+00:00"
  }
}

account.updated

Sendes når et hvilket som helst felt på en konto endres. Payload-skjemaet er identisk med account.created.

{
  "event": "account.updated",
  "data": {
    "uuid": "5c838347-d3ce-40fb-951c-b3190ccf2cba",
    "code": "important_client",
    "company_name": "Important client",
    "legal_address": "Important street 12",
    "legal_zipcode": "1234",
    "legal_city": "Aarhus",
    "legal_country": "DK",
    "legal_vat_number": "DK12345678",
    "billing_same_as_legal": true,
    "billing_address": null,
    "billing_zipcode": null,
    "billing_city": null,
    "billing_country": null,
    "created_date": "2018-11-20T11:25:23.889915+00:00"
  }
}

plan_terms.created

Mulige verdier for plan_vat_type: physical, services, unknown.

{
  "event": "plan_terms.created",
  "data": {
    "uuid": "b84948d2-30b8-4060-a5b4-6aa92db59b50",
    "plan_uuid": "5c838347-d3ce-40fb-951c-b3190ccf2cba",
    "plan_name": "Enterprise",
    "plan_collect_vat": true,
    "plan_vat_type": "services",
    "interval_type": "month",
    "interval_count": 1,
    "price": 99.99,
    "currency": "DKK"
  }
}

plan_terms.updated

{
  "event": "plan_terms.updated",
  "data": {
    "uuid": "b84948d2-30b8-4060-a5b4-6aa92db59b50",
    "plan_uuid": "5c838347-d3ce-40fb-951c-b3190ccf2cba",
    "plan_name": "Enterprise",
    "plan_collect_vat": true,
    "plan_vat_type": "services",
    "interval_type": "month",
    "interval_count": 1,
    "price": 99.99,
    "currency": "DKK"
  }
}

new_invoice

Mulige verdier for status: open, due, paid, nonpayment. Mulige verdier for collection_method: payment_card, invoice.

{
  "event": "new_invoice",
  "data": {
    "uuid": "b84948d2-30b8-4060-a5b4-6aa92db59b50",
    "invoice_number": 2193,
    "account_uuid": "5c838347-d3ce-40fb-951c-b3190ccf2cba",
    "account_code": "important_client",
    "date": "2018-11-20T11:25:23.889915+00:00",
    "due_date": "2018-11-30T11:25:23.889915+00:00",
    "invoice_api_url": "https://app.fenerum.com/api/v1/invoices/b84948d2-30b8-4060-a5b4-6aa92db59b50/",
    "currency": "DKK",
    "status": "open",
    "collection_method": "payment_card"
  }
}

paid_invoice

{
  "event": "paid_invoice",
  "data": {
    "uuid": "b84948d2-30b8-4060-a5b4-6aa92db59b50",
    "invoice_number": 2193,
    "account_uuid": "5c838347-d3ce-40fb-951c-b3190ccf2cba",
    "account_code": "important_client",
    "date": "2018-11-20T11:25:23.889915+00:00",
    "due_date": "2018-11-30T11:25:23.889915+00:00",
    "invoice_api_url": "https://app.fenerum.com/api/v1/invoices/b84948d2-30b8-4060-a5b4-6aa92db59b50/",
    "currency": "DKK",
    "status": "paid",
    "collection_method": "payment_card"
  }
}

invoice.overdue

Sendes når en faktura passerer sin due_date uten å være betalt. Payload-skjemaet er identisk med new_invoice.

cancel_subscription

Mulige verdier for collection_method: payment_card, invoice.

{
  "event": "cancel_subscription",
  "data": {
    "uuid": "b84948d2-30b8-4060-a5b4-6aa92db59b50",
    "account_uuid": "5c838347-d3ce-40fb-951c-b3190ccf2cba",
    "account_code": "important_client",
    "terms_uuid": "320ac230-a004-4cb3-9caa-fca0bee3e053",
    "start_date": "2018-01-21T11:25:23.889915+00:00",
    "end_date": null,
    "next_renewal_date": "2018-11-21T11:25:23.889915+00:00",
    "quantity": 1.5,
    "collection_method": "payment_card",
    "payment_terms": 10,
    "po_number": "A21"
  }
}

reactivate_subscription

Sendes når et tidligere oppsagt abonnement blir reaktivert. Payload-skjemaet er identisk med cancel_subscription.

renew_subscription_soon

Sendes når et abonnement skal fornyes i løpet av de neste 2 timene.

{
  "event": "renew_subscription_soon",
  "data": {
    "uuid": "b84948d2-30b8-4060-a5b4-6aa92db59b50",
    "account_uuid": "5c838347-d3ce-40fb-951c-b3190ccf2cba",
    "account_code": "important_client",
    "terms_uuid": "320ac230-a004-4cb3-9caa-fca0bee3e053",
    "start_date": "2018-01-21T11:25:23.889915+00:00",
    "end_date": null,
    "next_renewal_date": "2018-11-21T11:25:23.889915+00:00",
    "quantity": 1.5,
    "collection_method": "payment_card",
    "payment_terms": 10,
    "po_number": "A21"
  }
}

new_activity

Sendes ved abonnementrelatert aktivitet: nytt abonnement, fornyelse, oppsigelse, oppgradering, nedgradering osv. Fokuserer på den finansielle effekten av handlingen.

Mulige verdier for type: new, reactivate, renew, cancel, upgrade_qty, downgrade_qty, upgrade_subscription, downgraded_subscription, modified.

old_mrr, new_mrr og mrr_change har alltid to desimaler og serialiseres som strenger for å unngå presisjonstap.

{
  "event": "new_activity",
  "data": {
    "uuid": "b84948d2-30b8-4060-a5b4-6aa92db59b50",
    "account_uuid": "5c838347-d3ce-40fb-951c-b3190ccf2cba",
    "account_code": "important_client",
    "subscription": "320ac230-a004-4cb3-9caa-fca0bee3e053",
    "invoice": "e947c739-0e32-4954-aa78-9ec8605d58d5",
    "date": "2018-01-21T11:25:23.889915+00:00",
    "type": "upgrade_qty",
    "old_mrr": "150.30",
    "new_mrr": "200.40",
    "old_quantity": 3,
    "new_quantity": 4,
    "old_terms": "580eb744-8746-4e78-85a3-b927605db7ad",
    "new_terms": "580eb744-8746-4e78-85a3-b927605db7ad",
    "mrr_change": "50.10",
    "quantity_change": 1
  }
}

payment.authentication_required

Sendes når en kortbetaling ikke kan fullføres fordi kortholder må utføre ytterligere autentisering (f.eks. 3-D Secure / SCA-utfordring). Ikke aktivert som standard — aktiver den eksplisitt på din webhook.

{
  "event": "payment.authentication_required",
  "data": {
    "id": "1421",
    "payment_card": {
      "card_uuid": "f4293c5e-b592-43a1-9c68-eb76f62f6250",
      "card_number": "**** **** **** 4242",
      "payment_gateway_id": "card_1Nw3eQ2eZvKYlo2C7Lz5xxxx"
    },
    "amount": "199.00",
    "currency": "EUR",
    "payment_gateway": "stripe",
    "payment_gateway_id": "pi_3Nw3fQ2eZvKYlo2C0xx5xxxx",
    "invoice": "b84948d2-30b8-4060-a5b4-6aa92db59b50"
  }
}

payment.declined

Sendes når et forsøk på kortbetaling blir avslått av betalingsgatewayen.

Mulige verdier for payment_status: initial, pending, success, declined, canceled, pending_cancel. Mulige verdier for reason_code: auth_required, declined. Mulige verdier for type: payment, chargeback.

{
  "event": "payment.declined",
  "data": {
    "type": "payment",
    "reason": "Your card was declined.",
    "reason_code": "declined",
    "payment_status": "declined",
    "amount": "199.00",
    "amount_in_default_currency": "1485.00",
    "invoice": "b84948d2-30b8-4060-a5b4-6aa92db59b50",
    "date": "2026-05-18",
    "currency": "EUR",
    "payment_card_id": 1421,
    "data": {}
  }
}

data er et gateway-spesifikt JSON-objekt — strukturen avhenger av betalingsgatewayen og kan inkludere den rå feilmeldingen fra den underliggende leverandøren.

card_expires_this_month

Sendes én gang per kort i måneden kortet utløper, slik at du kan be kunden oppdatere betalingsmetoden før automatisk fornyelse mislykkes. Ikke aktivert som standard — aktiver den eksplisitt på din webhook. Levering med lav prioritet.

Mulige verdier for payment_gateway: stripe, quickpay.

{
  "event": "card_expires_this_month",
  "data": {
    "uuid": "f4293c5e-b592-43a1-9c68-eb76f62f6250",
    "active": true,
    "brand": "Visa",
    "card_number": "**** **** **** 4242",
    "month": 5,
    "year": 2026,
    "name": "Jane Doe",
    "payment_gateway": "stripe",
    "payment_gateway_id": "card_1Nw3eQ2eZvKYlo2C7Lz5xxxx",
    "account": "5c838347-d3ce-40fb-951c-b3190ccf2cba"
  }
}

payment_card.activated

Sendes når et betalingskort går over i aktiv tilstand på en konto (nyregistrert kort eller et tidligere inaktivt kort blir aktivt). Payload-skjemaet er identisk med card_expires_this_month. Ikke aktivert som standard — aktiver den eksplisitt på din webhook.

{
  "event": "payment_card.activated",
  "data": {
    "uuid": "f4293c5e-b592-43a1-9c68-eb76f62f6250",
    "active": true,
    "brand": "Visa",
    "card_number": "**** **** **** 4242",
    "month": 5,
    "year": 2028,
    "name": "Jane Doe",
    "payment_gateway": "stripe",
    "payment_gateway_id": "card_1Nw3eQ2eZvKYlo2C7Lz5xxxx",
    "account": "5c838347-d3ce-40fb-951c-b3190ccf2cba"
  }
}

payment_card.deactivated

Sendes når et betalingskort blir inaktivt (deaktivert av en API-innringer, utløpt eller fjernet av gatewayen). Payload-skjemaet er identisk med card_expires_this_month. Ikke aktivert som standard — aktiver den eksplisitt på din webhook.

{
  "event": "payment_card.deactivated",
  "data": {
    "uuid": "f4293c5e-b592-43a1-9c68-eb76f62f6250",
    "active": false,
    "brand": "Visa",
    "card_number": "**** **** **** 4242",
    "month": 5,
    "year": 2026,
    "name": "Jane Doe",
    "payment_gateway": "stripe",
    "payment_gateway_id": "card_1Nw3eQ2eZvKYlo2C7Lz5xxxx",
    "account": "5c838347-d3ce-40fb-951c-b3190ccf2cba"
  }
}