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": {}
}| Field | Type | Meaning |
|---|---|---|
event_id | integer | Unique id of the event. Use it to drop duplicates. |
business_slug | string | The business the event belongs to. Same value as {business_slug} in API paths. |
action | string | What happened. See Events. |
timestamp | string | When the event happened. ISO 8601 with a UTC offset. |
resource | string or null | The kind of object the event is about. See Resources. null when the event has no object. |
resource_id | integer or null | The id of that object. null when the event has no object. |
object_type | string or null | Internal model name of the object. Prefer resource. |
object_id | integer or null | Same value as resource_id. Kept for compatibility. |
extra | object | Event-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.
resource | Read it from |
|---|---|
business | GET /v1/business/{business_slug}/ |
document | GET /v1/business/{business_slug}/document/{resource_id}/ |
file | GET /v1/business/{business_slug}/files/{resource_id}/ |
folder | Folders in the API reference |
contact | GET /v1/business/{business_slug}/contacts/{resource_id}/ |
account | GET /v1/business/{business_slug}/account/{resource_id}/ |
period | GET /v1/business/{business_slug}/period/{resource_id}/ |
vat_period | GET /v1/business/{business_slug}/vat_period/{resource_id}/ |
tag | GET /v1/business/{business_slug}/tags/{resource_id}/ |
invoice | GET /v1/invoicing/{business_slug}/invoice/{resource_id}/ |
purchase_invoice | GET /v1/invoicing/{business_slug}/purchase_invoice/{resource_id}/ |
product | GET /v1/invoicing/{business_slug}/product/{resource_id}/ |
accounting_rule, expense_claim, workflow, suggestion, usership, comment | The 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:
| Event | Keys in extra |
|---|---|
DOCUMENT_CREATED for a purchase invoice | purchase_invoice_id, document_id |
DOCUMENT_DELETED for an expense claim | expense_claim_id |
FILE_UPLOADED_VIA_EMAIL | email (the address the file was sent to) |
| Any change made through the NoCFO app | client_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
action | resource | Sent when |
|---|---|---|
BUSINESS_UPDATED | business | Business settings change. |
BUSINESS_DELETED | business | The business is deleted. |
INVITATION_CREATED | invitation | A user is invited to the business. |
INVITATION_ACCEPTED | invitation | An invitation is accepted. |
INVITATION_REJECTED | invitation | An invitation is declined. |
USERSHIP_CREATED | usership | A user gets access to the business. |
USERSHIP_UPDATED | usership | A user's role or permissions change. |
USERSHIP_DELETED | usership | A user loses access. |
Bookkeeping documents
action | resource | Sent when |
|---|---|---|
DOCUMENT_CREATED | document | A document is created, including from a sales or purchase invoice. |
DOCUMENT_UPDATED | document | A document changes. |
DOCUMENT_DRAFT_ACCEPTED | document | A draft document is accepted. |
DOCUMENT_LOCKED | document | A document is locked. |
DOCUMENT_UNLOCKED | document | A document is unlocked. |
DOCUMENT_FLAGGED | document | A document is flagged for attention. |
DOCUMENT_UNFLAGGED | document | The flag is removed. |
DOCUMENT_ATTACHMENTS_LINKED | document | Files are attached to a document. |
DOCUMENT_ATTACHMENTS_REMOVED | document | Files are detached from a document. |
DOCUMENT_BANK_MISMATCH_IGNORED | document | A bank mismatch warning is dismissed. |
DOCUMENT_BANK_MISMATCH_SHOWN | document | A dismissed bank mismatch warning is shown again. |
DOCUMENT_DELETED | document | A document is deleted. |
ACCOUNTING_SUGGESTION_UPDATED | suggestion | A bookkeeping suggestion changes. |
ACCOUNTING_SUGGESTION_ACCEPTED | suggestion | A suggestion is accepted and booked. |
ACCOUNTING_SUGGESTION_REJECTED | suggestion | A suggestion is rejected. |
COMMENT_CREATED | comment | A comment is added. |
COMMENT_DELETED | comment | A comment is deleted. |
Files and folders
action | resource | Sent when |
|---|---|---|
FILE_UPLOADED | file | A file is uploaded. |
FILE_UPLOADED_VIA_EMAIL | file | A file arrives through the business's receiving email address. |
FILE_UPDATED | file | A file's details change. |
FILE_MOVED | file | A file is moved to another folder. |
FILE_DELETED | file | A file is deleted. |
FILE_MALWARE_DETECTED | file | The virus scan flags a file. |
FOLDER_CREATED | folder | A folder is created. |
FOLDER_UPDATED | folder | A folder changes. |
FOLDER_DELETED | folder | A folder is deleted. |
Sales invoices
action | resource | Sent when |
|---|---|---|
INVOICE_CREATED | invoice | A sales invoice is created. |
INVOICE_UPDATED | invoice | A sales invoice changes. |
INVOICE_ACCEPTED | invoice | A draft invoice is accepted. |
INVOICE_SENT_VIA_EMAIL | invoice | The invoice is sent by email. |
INVOICE_SENT_VIA_EINVOICE | invoice | The invoice is sent as an e-invoice. |
INVOICE_SENT_VIA_ELASKU | invoice | The invoice is sent as a consumer e-invoice (e-lasku). |
INVOICE_SENT_VIA_LETTER | invoice | The invoice is sent as a paper letter. |
INVOICE_SENT_VIA_SELF_PRINT | invoice | The invoice is marked as sent by the user (printed or sent outside NoCFO). |
INVOICE_SET_AS_PAID | invoice | The invoice is marked paid, by a user or by a matched payment. |
INVOICE_SET_AS_CREDIT_LOSS | invoice | The invoice is written off as a credit loss. |
INVOICE_RECURRENCE_DISABLED | invoice | Recurrence is turned off. |
INVOICE_DELETED | invoice | A sales invoice is deleted. |
Purchase invoices and payments
action | resource | Sent when |
|---|---|---|
EINVOICE_RECEIVED | purchase_invoice | A purchase invoice arrives as an e-invoice. |
PURCHASE_INVOICE_SET_AS_PAID | purchase_invoice | A purchase invoice is marked paid. |
PAYMENT_INSTRUCTION_CREATED | payment instruction | A payment is started for a purchase invoice. |
SALARY_PAID | salary | A salary payment is recorded from the payroll integration. |
Contacts, products, and expense claims
action | resource | Sent when |
|---|---|---|
CONTACT_CREATED | contact | A contact is created, including by import. |
CONTACT_UPDATED | contact | A contact changes. |
CONTACT_DELETED | contact | A contact is deleted. |
PRODUCT_CREATED | product | A product is created. |
PRODUCT_UPDATED | product | A product changes. |
PRODUCT_DELETED | product | A product is deleted. |
EXPENSE_CLAIM_CREATED | expense_claim | An expense claim, expense, or trip is created. |
EXPENSE_CLAIM_UPDATED | expense_claim | An expense claim changes. |
EXPENSE_CLAIM_DELETED | expense_claim | An expense claim is deleted. |
Chart of accounts, rules, and tags
action | resource | Sent when |
|---|---|---|
ACCOUNT_CREATED | account | An account is created. |
ACCOUNT_UPDATED | account | An account changes. |
ACCOUNT_SET_HIDDEN | account | An account is hidden. |
ACCOUNT_SET_SHOWN | account | A hidden account is shown again. |
ACCOUNT_DELETED | account | An account is deleted. |
ACCOUNTING_RULE_CREATED | accounting_rule | An accounting rule is created. |
ACCOUNTING_RULE_UPDATED | accounting_rule | An accounting rule changes. |
ACCOUNTING_RULE_APPLIED | accounting_rule | A rule is run on matching bank transactions. |
ACCOUNTING_RULE_DELETED | accounting_rule | An accounting rule is deleted. |
TAG_CREATED | tag | A tag is created. |
TAG_UPDATED | tag | A tag changes. |
TAG_DELETED | tag | A tag is deleted. |
Accounting periods
action | resource | Sent when |
|---|---|---|
PERIOD_CREATED | period | An accounting period is created. |
PERIOD_UPDATED | period | An accounting period changes. |
PERIOD_DELETED | period | An accounting period is deleted. |
PERIOD_LOCKED | period | A period is locked. |
PERIOD_UNLOCKED | period | A period is unlocked. |
PERIOD_ENSURED | period | Period checks are run. |
PERIOD_DEPRECATIONS_RECORDED | period | Depreciation entries are recorded. |
PERIOD_DEPRECATIONS_SKIPPED | period | Depreciation is skipped for the period. |
PERIOD_DEPRECATIONS_ENSURED | period | Depreciation entries are checked. |
PERIOD_DEFERRALS_RECORDED | period | Accrual entries are recorded. |
PERIOD_TAXES_RECORDED | period | Income tax entries are recorded. |
VAT periods
action | resource | Sent when |
|---|---|---|
VAT_PERIOD_CREATED | vat_period | A VAT period is created. |
VAT_PERIOD_UPDATED | vat_period | A VAT period changes. |
VAT_PERIOD_DELETED | vat_period | A VAT period is deleted. |
VAT_PERIOD_LOCKED | vat_period | A VAT period is locked. |
VAT_PERIOD_UNLOCKED | vat_period | A VAT period is unlocked. |
VAT_PERIOD_REPORTED | vat_period | A VAT period is marked as reported. |
VAT_PERIOD_SENT_TO_VEROHALLINTO | vat_period | The VAT return is sent to the Finnish Tax Administration. |
VAT_PERIOD_SENT_TO_ELSTER | vat_period | The VAT return is sent to ELSTER (Germany). |
Bank and Holvi integrations
action | resource | Sent when |
|---|---|---|
BANK_INTEGRATION_CREATED | bank integration | A bank connection is set up. |
BANK_INTEGRATION_RENEWED | bank integration | A bank connection is re-authorized. |
BANK_INTEGRATION_UPDATED | bank integration | Bank connection settings change. |
BANK_INTEGRATION_ACCOUNT_STALED | bank integration | A bank account stops syncing. |
BANK_INTEGRATION_DELETED | bank integration | A bank connection is removed. |
NOTIFICATION_BANK_INTEGRATION_EXPIRY | bank integration | A bank connection is about to expire. |
HOLVI_INTEGRATION_CREATED | null | Holvi is connected. |
HOLVI_INTEGRATION_RECONNECTED | null | Holvi is connected again. |
HOLVI_INTEGRATION_UPDATED | Holvi account | Holvi account settings change. |
HOLVI_INTEGRATION_STALED | business | The Holvi connection stops working. |
HOLVI_INTEGRATION_DELETED | null | Holvi is disconnected. |
Workflows
action | resource | Sent when |
|---|---|---|
WORKFLOW_CREATED | workflow | A workflow is created. |
WORKFLOW_UPDATED | workflow | A workflow changes. |
WORKFLOW_DELETED | workflow | A 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_idyou 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.