Developers
Using the API

Webhook events

What a webhook delivery contains, and which events NoCFO sends.

A webhook tells you that something changed in a business. It does not carry the changed data. Read the resource from the API when you need its current state.

Set up a subscription first. See Webhooks.

Payload

Every delivery is one POST with a JSON body. One delivery is one event.

{
  "event_id": 48213377,
  "business_slug": "acme-oy",
  "action": "INVOICE_SENT_VIA_EMAIL",
  "timestamp": "2026-11-20T08:15:30.123456+00:00",
  "object_type": "invoicemodel",
  "object_id": 1042,
  "resource": "invoice",
  "resource_id": 1042,
  "extra": {}
}
FieldTypeMeaning
event_idintegerUnique id of the event. Use it to drop duplicates.
business_slugstringThe business the event belongs to. Same value as {business_slug} in API paths.
actionstringWhat happened. See Events.
timestampstringWhen the event happened. ISO 8601 with a UTC offset.
resourcestring or nullThe kind of object the event is about. See Resources. null when the event has no object.
resource_idinteger or nullThe id of that object. null when the event has no object.
object_typestring or nullInternal model name of the object. Prefer resource.
object_idinteger or nullSame value as resource_id. Kept for compatibility.
extraobjectEvent-specific details. Often empty. See Extra.

The payload does not include the user who made the change, or the object's fields.

Resources

resource tells you where to read the object.

resourceRead it from
businessGET /v1/business/{business_slug}/
documentGET /v1/business/{business_slug}/document/{resource_id}/
fileGET /v1/business/{business_slug}/files/{resource_id}/
folderFolders in the API reference
contactGET /v1/business/{business_slug}/contacts/{resource_id}/
accountGET /v1/business/{business_slug}/account/{resource_id}/
periodGET /v1/business/{business_slug}/period/{resource_id}/
vat_periodGET /v1/business/{business_slug}/vat_period/{resource_id}/
tagGET /v1/business/{business_slug}/tags/{resource_id}/
invoiceGET /v1/invoicing/{business_slug}/invoice/{resource_id}/
purchase_invoiceGET /v1/invoicing/{business_slug}/purchase_invoice/{resource_id}/
productGET /v1/invoicing/{business_slug}/product/{resource_id}/
accounting_rule, expense_claim, workflow, suggestion, usership, commentThe matching section of the API reference

Some events point at objects that have no public endpoint, such as a bank integration. For those, resource is an internal model name. Treat an unknown resource as "something changed" and ignore it, or refresh what you depend on.

After a *_DELETED event the object is gone. A read returns 404.

Extra

extra holds details that only some events have. Examples:

EventKeys in extra
DOCUMENT_CREATED for a purchase invoicepurchase_invoice_id, document_id
DOCUMENT_DELETED for an expense claimexpense_claim_id
FILE_UPLOADED_VIA_EMAILemail (the address the file was sent to)
Any change made through the NoCFO appclient_mutation_id may appear. It is used by the NoCFO app. Ignore it.

The keys in extra are not a stable contract. Do not fail if a key is missing or a new key appears. Read the resource from the API for data you rely on.

Events

action is one of the values below. New values can be added at any time. Ignore an action you do not handle and answer it with 2xx, so NoCFO does not retry it.

The resource column is the usual value of resource for that event.

Business and people

actionresourceSent when
BUSINESS_UPDATEDbusinessBusiness settings change.
BUSINESS_DELETEDbusinessThe business is deleted.
INVITATION_CREATEDinvitationA user is invited to the business.
INVITATION_ACCEPTEDinvitationAn invitation is accepted.
INVITATION_REJECTEDinvitationAn invitation is declined.
USERSHIP_CREATEDusershipA user gets access to the business.
USERSHIP_UPDATEDusershipA user's role or permissions change.
USERSHIP_DELETEDusershipA user loses access.

Bookkeeping documents

actionresourceSent when
DOCUMENT_CREATEDdocumentA document is created, including from a sales or purchase invoice.
DOCUMENT_UPDATEDdocumentA document changes.
DOCUMENT_DRAFT_ACCEPTEDdocumentA draft document is accepted.
DOCUMENT_LOCKEDdocumentA document is locked.
DOCUMENT_UNLOCKEDdocumentA document is unlocked.
DOCUMENT_FLAGGEDdocumentA document is flagged for attention.
DOCUMENT_UNFLAGGEDdocumentThe flag is removed.
DOCUMENT_ATTACHMENTS_LINKEDdocumentFiles are attached to a document.
DOCUMENT_ATTACHMENTS_REMOVEDdocumentFiles are detached from a document.
DOCUMENT_BANK_MISMATCH_IGNOREDdocumentA bank mismatch warning is dismissed.
DOCUMENT_BANK_MISMATCH_SHOWNdocumentA dismissed bank mismatch warning is shown again.
DOCUMENT_DELETEDdocumentA document is deleted.
ACCOUNTING_SUGGESTION_UPDATEDsuggestionA bookkeeping suggestion changes.
ACCOUNTING_SUGGESTION_ACCEPTEDsuggestionA suggestion is accepted and booked.
ACCOUNTING_SUGGESTION_REJECTEDsuggestionA suggestion is rejected.
COMMENT_CREATEDcommentA comment is added.
COMMENT_DELETEDcommentA comment is deleted.

Files and folders

actionresourceSent when
FILE_UPLOADEDfileA file is uploaded.
FILE_UPLOADED_VIA_EMAILfileA file arrives through the business's receiving email address.
FILE_UPDATEDfileA file's details change.
FILE_MOVEDfileA file is moved to another folder.
FILE_DELETEDfileA file is deleted.
FILE_MALWARE_DETECTEDfileThe virus scan flags a file.
FOLDER_CREATEDfolderA folder is created.
FOLDER_UPDATEDfolderA folder changes.
FOLDER_DELETEDfolderA folder is deleted.

Sales invoices

actionresourceSent when
INVOICE_CREATEDinvoiceA sales invoice is created.
INVOICE_UPDATEDinvoiceA sales invoice changes.
INVOICE_ACCEPTEDinvoiceA draft invoice is accepted.
INVOICE_SENT_VIA_EMAILinvoiceThe invoice is sent by email.
INVOICE_SENT_VIA_EINVOICEinvoiceThe invoice is sent as an e-invoice.
INVOICE_SENT_VIA_ELASKUinvoiceThe invoice is sent as a consumer e-invoice (e-lasku).
INVOICE_SENT_VIA_LETTERinvoiceThe invoice is sent as a paper letter.
INVOICE_SENT_VIA_SELF_PRINTinvoiceThe invoice is marked as sent by the user (printed or sent outside NoCFO).
INVOICE_SET_AS_PAIDinvoiceThe invoice is marked paid, by a user or by a matched payment.
INVOICE_SET_AS_CREDIT_LOSSinvoiceThe invoice is written off as a credit loss.
INVOICE_RECURRENCE_DISABLEDinvoiceRecurrence is turned off.
INVOICE_DELETEDinvoiceA sales invoice is deleted.

Purchase invoices and payments

actionresourceSent when
EINVOICE_RECEIVEDpurchase_invoiceA purchase invoice arrives as an e-invoice.
PURCHASE_INVOICE_SET_AS_PAIDpurchase_invoiceA purchase invoice is marked paid.
PAYMENT_INSTRUCTION_CREATEDpayment instructionA payment is started for a purchase invoice.
SALARY_PAIDsalaryA salary payment is recorded from the payroll integration.

Contacts, products, and expense claims

actionresourceSent when
CONTACT_CREATEDcontactA contact is created, including by import.
CONTACT_UPDATEDcontactA contact changes.
CONTACT_DELETEDcontactA contact is deleted.
PRODUCT_CREATEDproductA product is created.
PRODUCT_UPDATEDproductA product changes.
PRODUCT_DELETEDproductA product is deleted.
EXPENSE_CLAIM_CREATEDexpense_claimAn expense claim, expense, or trip is created.
EXPENSE_CLAIM_UPDATEDexpense_claimAn expense claim changes.
EXPENSE_CLAIM_DELETEDexpense_claimAn expense claim is deleted.

Chart of accounts, rules, and tags

actionresourceSent when
ACCOUNT_CREATEDaccountAn account is created.
ACCOUNT_UPDATEDaccountAn account changes.
ACCOUNT_SET_HIDDENaccountAn account is hidden.
ACCOUNT_SET_SHOWNaccountA hidden account is shown again.
ACCOUNT_DELETEDaccountAn account is deleted.
ACCOUNTING_RULE_CREATEDaccounting_ruleAn accounting rule is created.
ACCOUNTING_RULE_UPDATEDaccounting_ruleAn accounting rule changes.
ACCOUNTING_RULE_APPLIEDaccounting_ruleA rule is run on matching bank transactions.
ACCOUNTING_RULE_DELETEDaccounting_ruleAn accounting rule is deleted.
TAG_CREATEDtagA tag is created.
TAG_UPDATEDtagA tag changes.
TAG_DELETEDtagA tag is deleted.

Accounting periods

actionresourceSent when
PERIOD_CREATEDperiodAn accounting period is created.
PERIOD_UPDATEDperiodAn accounting period changes.
PERIOD_DELETEDperiodAn accounting period is deleted.
PERIOD_LOCKEDperiodA period is locked.
PERIOD_UNLOCKEDperiodA period is unlocked.
PERIOD_ENSUREDperiodPeriod checks are run.
PERIOD_DEPRECATIONS_RECORDEDperiodDepreciation entries are recorded.
PERIOD_DEPRECATIONS_SKIPPEDperiodDepreciation is skipped for the period.
PERIOD_DEPRECATIONS_ENSUREDperiodDepreciation entries are checked.
PERIOD_DEFERRALS_RECORDEDperiodAccrual entries are recorded.
PERIOD_TAXES_RECORDEDperiodIncome tax entries are recorded.

VAT periods

actionresourceSent when
VAT_PERIOD_CREATEDvat_periodA VAT period is created.
VAT_PERIOD_UPDATEDvat_periodA VAT period changes.
VAT_PERIOD_DELETEDvat_periodA VAT period is deleted.
VAT_PERIOD_LOCKEDvat_periodA VAT period is locked.
VAT_PERIOD_UNLOCKEDvat_periodA VAT period is unlocked.
VAT_PERIOD_REPORTEDvat_periodA VAT period is marked as reported.
VAT_PERIOD_SENT_TO_VEROHALLINTOvat_periodThe VAT return is sent to the Finnish Tax Administration.
VAT_PERIOD_SENT_TO_ELSTERvat_periodThe VAT return is sent to ELSTER (Germany).

Bank and Holvi integrations

actionresourceSent when
BANK_INTEGRATION_CREATEDbank integrationA bank connection is set up.
BANK_INTEGRATION_RENEWEDbank integrationA bank connection is re-authorized.
BANK_INTEGRATION_UPDATEDbank integrationBank connection settings change.
BANK_INTEGRATION_ACCOUNT_STALEDbank integrationA bank account stops syncing.
BANK_INTEGRATION_DELETEDbank integrationA bank connection is removed.
NOTIFICATION_BANK_INTEGRATION_EXPIRYbank integrationA bank connection is about to expire.
HOLVI_INTEGRATION_CREATEDnullHolvi is connected.
HOLVI_INTEGRATION_RECONNECTEDnullHolvi is connected again.
HOLVI_INTEGRATION_UPDATEDHolvi accountHolvi account settings change.
HOLVI_INTEGRATION_STALEDbusinessThe Holvi connection stops working.
HOLVI_INTEGRATION_DELETEDnullHolvi is disconnected.

Workflows

actionresourceSent when
WORKFLOW_CREATEDworkflowA workflow is created.
WORKFLOW_UPDATEDworkflowA workflow changes.
WORKFLOW_DELETEDworkflowA workflow is deleted.

Other events

You can also receive events about the business's NoCFO subscription, billing, and referrals. Examples are PLAN_UPGRADED, PLAN_DEGRADED, STRIPE_UNPAID_LOCK_ADDED, STRIPE_UNPAID_LOCK_REMOVED, LUCA_CREDIT_BUNDLE_PURCHASED, and REFERRAL_CONVERTED. They describe the business's own NoCFO account, not its bookkeeping. Most integrations ignore them.

Handling deliveries

  • Check the basic-auth credentials before you trust the body.
  • Answer with 2xx quickly. Do the work after you answer, for example in a queue. NoCFO waits 10 seconds.
  • Drop an event_id you have already processed. The same event can arrive more than once.
  • Do not rely on order. Deliveries can arrive out of order. Compare timestamp, or read the current state from the API.
  • Read the resource from the API when you need its data. Several events in a row for one object can collapse into one read.

On this page