Webhook callbacks

When events occur in Fenerum, an HTTP POST request is sent to every enabled endpoint configured on every Webhook. Each request body has an event field identifying the event type and a data field carrying a snapshot of the resource. Endpoints should respond with any 2XX status to acknowledge receipt.

Most events are subscribed to by default when a webhook is created. The payment-related events (payment.authentication_required, payment.declined, card_expires_this_month, payment_card.activated, payment_card.deactivated) are not enabled by default — opt in explicitly via the events field on the Webhook resource.

A subset of these events is also visible in the Swagger console under the Webhook callbacks tag.

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

Sent when any field on an account changes. Payload schema matches 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

Possible values of 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

Possible values of status: open, due, paid, nonpayment. Possible values of 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

Sent when an invoice passes its due_date without being paid. Payload schema matches new_invoice.

cancel_subscription

Possible values of 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

Sent when a previously-cancelled subscription is reactivated. Payload schema matches cancel_subscription.

renew_subscription_soon

Sent when a subscription is due to be renewed in the next 2 hours.

{
  "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

Sent on a subscription-related activity: new subscription, renewal, cancellation, upgrade, downgrade, etc. Focuses on the financial impact of the action.

Possible values of type: new, reactivate, renew, cancel, upgrade_qty, downgrade_qty, upgrade_subscription, downgraded_subscription, modified.

old_mrr, new_mrr, and mrr_change always have two decimal places and are serialized as strings to avoid losing exactness.

{
  "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

Sent when a card payment cannot complete because the cardholder must perform additional authentication (e.g., 3-D Secure / SCA challenge). Not enabled by default — enable it explicitly on your 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

Sent when a card payment attempt is declined by the payment gateway.

Possible values of payment_status: initial, pending, success, declined, canceled, pending_cancel. Possible values of reason_code: auth_required, declined. Possible values of 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 is a gateway-specific JSON object — its shape depends on the payment gateway and may include the raw failure response from the upstream provider.

card_expires_this_month

Sent once per card during the month that the card expires, so you can prompt the customer to update their payment method before automatic renewal fails. Not enabled by default — enable it explicitly on your webhook. Low-priority delivery.

Possible values of 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

Sent when a payment card transitions to an active state on an account (newly registered card or a previously inactive card becoming active). Payload schema matches card_expires_this_month. Not enabled by default — enable it explicitly on your 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

Sent when a payment card becomes inactive (disabled by an API caller, expired, or removed by the gateway). Payload schema matches card_expires_this_month. Not enabled by default — enable it explicitly on your 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"
  }
}