Events

Reference for the Bkper event system — how to subscribe to events in bkper.yaml, the full Event object structure with book/user/agent/data fields, the complete current event type list, and how to use previousAttributes for diffs.

Bkper fires events whenever something changes in a Book — transactions created, accounts updated, collaborators added, and more. These events are the foundation for building automations with event handlers.

Subscribing to events

You declare which events your app receives in the events list of your bkper.yaml:

events:
    - TRANSACTION_CHECKED
    - TRANSACTION_POSTED
    - ACCOUNT_CREATED

When one of these events occurs in a Book where your app is installed, Bkper sends an HTTP POST to your configured webhook URL with the event payload.

The Event object

When an event handler receives an event, the payload has the following structure:

{
    /** The id of the Book associated to the Event */
    bookId?: string;

    /** The Book object associated with the Event */
    book?: {
        agentId?: string;
        collection?: Collection;
        createdAt?: string;
        datePattern?: string;
        decimalSeparator?: "DOT" | "COMMA";
        fractionDigits?: number;
        id?: string;
        lastUpdateMs?: string;
        lockDate?: string;
        name?: string;
        ownerName?: string;
        pageSize?: number;
        period?: "MONTH" | "QUARTER" | "YEAR";
        periodStartMonth?: "JANUARY" | "FEBRUARY" | "MARCH" | "APRIL"
            | "MAY" | "JUNE" | "JULY" | "AUGUST" | "SEPTEMBER"
            | "OCTOBER" | "NOVEMBER" | "DECEMBER";
        permission?: "OWNER" | "EDITOR" | "POSTER" | "RECORDER"
            | "VIEWER" | "NONE";
        properties?: { [name: string]: string };
        timeZone?: string;
        timeZoneOffset?: number;
    };

    /** The user in charge of the Event */
    user?: {
        avatarUrl?: string;
        name?: string;
        username?: string;
    };

    /** The Event agent, such as the App, Bot or Bank institution */
    agent?: {
        id?: string;
        logo?: string;
        name?: string;
    };

    /** The creation timestamp, in milliseconds */
    createdAt?: string;

    /** The event data */
    data?: {
        /**
         * The object payload. Depends on the event type.
         * For example, ACCOUNT_CREATED receives an Account payload.
         */
        object?: any;
        /** The object previous attributes when updated */
        previousAttributes?: { [name: string]: string };
    };

    /** The unique id that identifies the Event */
    id?: string;

    /** The resource associated to the Event */
    resource?: string;

    /** The type of the Event */
    type?: EventType;
}

The event payload is the same structure exposed by the REST API. If you use TypeScript, add the @bkper/bkper-api-types package to your project for full type definitions:

app.post('/', async c => {
    const event: bkper.Event = await c.req.json();
    // handle event...
});

Event types

The list below is the complete current set of event types for API v5.

Event	Description
`FILE_CREATED`	A file was attached to the book.
`FILE_UPDATED`	An attached file was updated.
`TRANSACTION_CREATED`	A draft transaction was created.
`TRANSACTION_UPDATED`	A transaction was updated.
`TRANSACTION_DELETED`	A transaction was deleted.
`TRANSACTION_POSTED`	A draft transaction was posted and now affects balances.
`TRANSACTION_CHECKED`	A posted transaction was checked (reviewed and locked).
`TRANSACTION_UNCHECKED`	A checked transaction was unchecked and becomes editable again.
`TRANSACTION_RESTORED`	A deleted transaction was restored.
`ACCOUNT_CREATED`	An account was created.
`ACCOUNT_UPDATED`	An account was updated.
`ACCOUNT_DELETED`	An account was deleted.
`QUERY_CREATED`	A saved query was created.
`QUERY_UPDATED`	A saved query was updated.
`QUERY_DELETED`	A saved query was deleted.
`GROUP_CREATED`	A group was created.
`GROUP_UPDATED`	A group was updated.
`GROUP_DELETED`	A group was deleted.
`COMMENT_CREATED`	A comment was added.
`COMMENT_DELETED`	A comment was deleted.
`COLLABORATOR_ADDED`	A collaborator was added to the book.
`COLLABORATOR_UPDATED`	A collaborator’s permissions were updated.
`COLLABORATOR_REMOVED`	A collaborator was removed from the book.
`INTEGRATION_CREATED`	An integration was created in the book.
`INTEGRATION_UPDATED`	An integration was updated.
`INTEGRATION_DELETED`	An integration was deleted.
`BOOK_CREATED`	A book was created.
`BOOK_AUDITED`	A balances audit completed for the book.
`BOOK_UPDATED`	Book settings were updated.
`BOOK_DELETED`	The book was deleted.

Event data

The data.object field contains the resource that was affected. Its shape depends on the event type:

Transaction events: The full Transaction object
Account events: The full Account object
Group events: The full Group object
Comment events: The Comment object
Collaborator events: The Collaborator object

For update events, data.previousAttributes contains the fields that changed and their previous values — useful for computing diffs or reacting only to specific field changes.

The `agent` field

Every event includes information about which agent triggered it. This is important for preventing loops — if your event handler creates a transaction, that will fire a new event, and you need to check event.agent.id to avoid reacting to your own actions.