Webhook-callbacks

Når der opstår events i Fenerum, sendes en HTTP POST-anmodning til hvert aktiveret endpoint, som er konfigureret på hver Webhook. Hver request-body indeholder et event-felt, der identificerer event-typen, og et data-felt, der bærer et snapshot af ressourcen. Endpoints bør svare med en vilkårlig 2XX-status for at bekræfte modtagelsen.

De fleste events abonneres der på som standard, når en webhook oprettes. De betalingsrelaterede events (payment.authentication_required, payment.declined, card_expires_this_month, payment_card.activated, payment_card.deactivated) er ikke aktiveret som standard — tilvælg dem eksplicit via feltet events på Webhook-ressourcen.

En delmængde af disse events er også synlig i Swagger-konsollen under tagget 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 vilkårligt felt på en konto ændres. Payload-schemaet matcher 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 værdier af 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 værdier af status: open, due, paid, nonpayment. Mulige værdier af 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 uden at blive betalt. Payload-schemaet matcher new_invoice.

cancel_subscription

Mulige værdier af 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 annulleret abonnement genaktiveres. Payload-schemaet matcher cancel_subscription.

renew_subscription_soon

Sendes, når et abonnement står til at blive fornyet inden for de næste 2 timer.

{
  "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 en abonnementsrelateret aktivitet: nyt abonnement, fornyelse, annullering, opgradering, nedgradering osv. Fokuserer på den økonomiske effekt af handlingen.

Mulige værdier af type: new, reactivate, renew, cancel, upgrade_qty, downgrade_qty, upgrade_subscription, downgraded_subscription, modified.

old_mrr, new_mrr og mrr_change har altid to decimaler og serialiseres som strenge for at undgå tab af nøjagtighed.

{
  "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 gennemføres, fordi kortholderen skal udføre yderligere autentifikation (fx 3-D Secure / SCA challenge). Ikke aktiveret som standard — aktiver den eksplicit 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øg på kortbetaling afvises af payment gateway'en.

Mulige værdier af payment_status: initial, pending, success, declined, canceled, pending_cancel. Mulige værdier af reason_code: auth_required, declined. Mulige værdier af 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 gatewayspecifikt JSON-objekt — dets struktur afhænger af payment gateway'en og kan inkludere den rå fejlsvarspayload fra upstream-udbyderen.

card_expires_this_month

Sendes én gang pr. kort i den måned, hvor kortet udløber, så du kan bede kunden opdatere deres betalingsmetode, før automatisk fornyelse fejler. Ikke aktiveret som standard — aktiver den eksplicit på din webhook. Levering med lav prioritet.

Mulige værdier af 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 overgår til en aktiv tilstand på en konto (nyregistreret kort eller et tidligere inaktivt kort, der bliver aktivt). Payload-schemaet matcher card_expires_this_month. Ikke aktiveret som standard — aktiver den eksplicit 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 bliver inaktivt (deaktiveret via API, udløbet eller fjernet af gateway'en). Payload-schemaet matcher card_expires_this_month. Ikke aktiveret som standard — aktiver den eksplicit 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"
  }
}