Webhook-callbackit

Kun Fenerumissa tapahtuu tapahtumia, HTTP POST -pyyntö lähetetään jokaiseen käytössä olevaan päätepisteeseen, joka on määritetty jokaisessa Webhook-resurssissa. Jokaisessa pyyntörungossa on event-kenttä, joka yksilöi tapahtumatyypin, sekä data-kenttä, joka sisältää tilannekuvan resurssista. Päätepisteiden tulisi vastata millä tahansa 2XX-statuskoodilla vastaanoton kuittaamiseksi.

Useimmat tapahtumat ovat oletuksena tilattuna, kun webhook luodaan. Maksuihin liittyvät tapahtumat (payment.authentication_required, payment.declined, card_expires_this_month, payment_card.activated, payment_card.deactivated) eivät ole oletuksena käytössä — ota ne erikseen käyttöön Webhook-resurssin events-kentässä.

Osa näistä tapahtumista on nähtävissä myös Swagger console:ssa Webhook callbacks -tunnisteen alla.

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

Lähetetään, kun mikä tahansa tilin kenttä muuttuu. Payloadin skeema vastaa account.created-tapahtumaa.

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

Mahdolliset plan_vat_type-arvot: 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

Mahdolliset status-arvot: open, due, paid, nonpayment. Mahdolliset collection_method-arvot: 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

Lähetetään, kun lasku ylittää due_date-määräpäivänsä eikä sitä ole maksettu. Payloadin skeema vastaa new_invoice-tapahtumaa.

cancel_subscription

Mahdolliset collection_method-arvot: 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

Lähetetään, kun aiemmin peruttu tilaus aktivoidaan uudelleen. Payloadin skeema vastaa cancel_subscription-tapahtumaa.

renew_subscription_soon

Lähetetään, kun tilaus on uusimassa seuraavien 2 tunnin aikana.

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

Lähetetään tilaukseen liittyvästä aktiviteetista: uusi tilaus, uusinta, peruutus, upgrade, downgrade jne. Keskittyy toimenpiteen taloudelliseen vaikutukseen.

Mahdolliset type-arvot: new, reactivate, renew, cancel, upgrade_qty, downgrade_qty, upgrade_subscription, downgraded_subscription, modified.

old_mrr, new_mrr ja mrr_change sisältävät aina kaksi desimaalia ja sarjoitetaan merkkijonoiksi tarkkuuden säilyttämiseksi.

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

Lähetetään, kun korttimaksua ei voida suorittaa loppuun, koska kortinhaltijan on tehtävä lisätodennus (esim. 3-D Secure / SCA -haaste). Ei oletuksena käytössä — ota se erikseen käyttöön webhookissasi.

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

Lähetetään, kun korttimaksuyritys hylätään maksuvälittäjän toimesta.

Mahdolliset payment_status-arvot: initial, pending, success, declined, canceled, pending_cancel. Mahdolliset reason_code-arvot: auth_required, declined. Mahdolliset type-arvot: 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 on maksuvälittäjäkohtainen JSON-objekti — sen rakenne riippuu käytetystä maksuvälittäjästä ja voi sisältää ylävirran palveluntarjoajan raakamuotoisen virhevastauksen.

card_expires_this_month

Lähetetään kerran kutakin korttia kohti sen kuukauden aikana, jolloin kortti vanhenee, jotta voit pyytää asiakasta päivittämään maksutapansa ennen automaattisen uusinnan epäonnistumista. Ei oletuksena käytössä — ota se erikseen käyttöön webhookissasi. Matalan prioriteetin toimitus.

Mahdolliset payment_gateway-arvot: 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

Lähetetään, kun maksukortti siirtyy tilillä aktiiviseen tilaan (uusi rekisteröity kortti tai aiemmin passiivinen kortti aktivoituu). Payloadin skeema vastaa card_expires_this_month-tapahtumaa. Ei oletuksena käytössä — ota se erikseen käyttöön webhookissasi.

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

Lähetetään, kun maksukortista tulee passiivinen (poistettu käytöstä API-kutsulla, vanhentunut tai poistettu maksuvälittäjän toimesta). Payloadin skeema vastaa card_expires_this_month-tapahtumaa. Ei oletuksena käytössä — ota se erikseen käyttöön webhookissasi.

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