Event types

When something changes, Ownrecord records an event in the same transaction as the change and delivers it to your webhook endpoints. Every delivery has this envelope:

{
  "id": "evt_01jz3k2m4n5p6q7r8s9t0v1w2x",
  "type": "customer.created",
  "created": 1791892800,
  "livemode": false,
  "data": {
    "object": {}
  },
  "previous_attributes": {}
}

created is when the event happened, in Unix seconds (the event feed, GET /api/v1/events, returns the same envelope). data.object is the object as it is after the change. previous_attributes holds the changed fields' old values, on update events only. Events can arrive out of order: use created, and fetch the object again when you need its latest state.

API key#

api_key.created#

An API key was created. The secret is never part of the event.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

api_key.revoked#

An API key was revoked. It stops working immediately.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

api_key.updated#

An API key was renamed. previous_attributes has the old name.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

App#

app.listing_approved#

Ownrecord approved an app's listing: it is listed for every organization, with a verified publisher, for the scopes approved.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

app.listing_changes_requested#

Ownrecord asked for changes to an app's listing application. reason says what to change; edit and submit it again.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

app.listing_rejected#

Ownrecord rejected an app's listing: other organizations can no longer install it. reason says why.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

app.reinstated#

Ownrecord lifted an app's suspension. Its installations stay paused until each organization resumes its own.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

app.suspended#

Ownrecord suspended an app everywhere: its tokens are revoked, its installations paused and the agents it owns stopped. reason says why.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

Approval#

approval.requested#

A call needed a person's approval, so an approval request was created instead of running it. Nothing ran yet.

Scope: Organization · Webhooks: delivered

data.object:

approval.resolved#

An approval request reached its outcome: executed (approved and run as requested), rejected, stale (approved, but it could no longer run as requested) or expired (nobody decided within 72 hours). status says which.

Scope: Organization · Webhooks: delivered

data.object:

Brand#

brand.created#

A brand was created under a legal entity. New brands start in test mode only (test_only).

Scope: Organization · Webhooks: not delivered (internal)

data.object:

brand.updated#

A brand's settings changed. previous_attributes has the old values.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

Checkout#

checkout.session.blocked#

The customer's details gave a tax quote Ownrecord can't charge with confidence (for example, the seller isn't registered where a zero threshold applies), so the sale is paused and the hosted page offers the waitlist. data.blockedReason is the reason code.

Scope: Brand · Webhooks: delivered

data.object:

checkout.session.completed#

A checkout was paid and fulfilled: the payment is recorded, the sale posted, the invoice issued and credit packs granted, all in one transaction triggered by the processor's webhook. data is the session with paymentId and invoiceId.

Scope: Brand · Webhooks: delivered

data.object:

checkout.session.expired#

A checkout session expired without a payment: its time ran out (24 hours by default) or it was expired through the API.

Scope: Brand · Webhooks: delivered

data.object:

Coupon#

coupon.created#

A coupon (percent or amount off, with a duration) was created in the brand's catalog.

Scope: Brand · Webhooks: delivered

data.object:

coupon.updated#

A coupon changed: its name, metadata or active (archived or reactivated), or, while unused, its terms. previous_attributes has the old values.

Scope: Brand · Webhooks: delivered

data.object:

Credit note#

credit_note.issued#

A credit note was issued for a refund: numbered without gaps in the brand's credit note series, it reverses the original invoice's lines at their original tax rates and jurisdictions. data is the credit note (credit_notes.get); its PDF is rendered and emailed to the customer right after (pdf.status turns ready).

Scope: Brand · Webhooks: delivered

data.object:

Customer#

customer.created#

A customer was created: through the API or the console, or by checkout for a new buyer. Tax IDs given at creation are already checked (taxIds[].verification).

Scope: Brand · Webhooks: delivered

data.object:

customer.credit_balance.updated#

A customer's credit balance changed in one currency: an operator adjusted it (with a reason), an invoice used it at finalization, a voided invoice gave it back, a subscription change credited unused time (proration), or a refund gave back the part of an invoice the balance paid (refund, M8). data.balance is the new balance and data.change the signed change, both in integer micros; data.reason says why (adjustment, invoice_applied, invoice_voided, proration, refund).

Scope: Brand · Webhooks: delivered

data.object:

customer.entitlements.updated#

A customer's entitlements changed: a subscription, lifetime purchase or override changed, the brand changed a feature or a product's entitlements, or an override expired or a past-due grace period ended. changes lists each feature whose value changed; previous_attributes.values has the previous set.

Scope: Brand · Webhooks: delivered

data.object:

customer.updated#

A customer changed: profile fields, tax IDs added or removed, the locked tax country set at the first payment or moved by a top-up, or the customer was deleted (deletedAt). previous_attributes has the old values of the fields that changed.

Scope: Brand · Webhooks: delivered

data.object:

Data export#

data_export.failed#

An accounting export couldn't be built; failure says why. Request it again.

Scope: Legal entity · Webhooks: delivered

data.object:

data_export.ready#

An accounting export's files (journal, invoice register, credit-note register) are ready to download for 30 days.

Scope: Legal entity · Webhooks: delivered

data.object:

data_export.requested#

An accounting export was requested (internal); the data_export job builds its files.

Scope: Legal entity · Webhooks: not delivered (internal)

data.object:

Discount#

discount.created#

A coupon was applied to a customer or a subscription (directly or through a promotion code), with the dates it covers.

Scope: Brand · Webhooks: delivered

data.object:

discount.deleted#

A discount was ended before its time: it no longer applies to invoices from end on. previous_attributes.end has the old end (null for forever).

Scope: Brand · Webhooks: delivered

data.object:

Dispute#

dispute.closed#

The processor closed a dispute. status is won (the withdrawn amount came back, the fee stays; an inquiry closes as won with nothing booked) or lost (the money stays withdrawn and the customer's risk becomes elevated).

Scope: Brand · Webhooks: delivered

data.object:

dispute.created#

A customer disputed a payment with their bank. For a chargeback the disputed amount and the dispute fee are booked as withdrawn; an inquiry (inquiry: true) takes no money and books nothing until the bank escalates it. The customer's wallets are frozen unless the brand turned that off.

Scope: Brand · Webhooks: delivered

data.object:

dispute.updated#

The processor withdrew the funds of an inquiry (it became a chargeback: inquiry: false, fundsWithdrawnAt, the chargeback posted), or the evidence pack was built or submitted, or the notes or assignee changed. previous_attributes has the old values.

Scope: Brand · Webhooks: delivered

data.object:

Einvoice#

einvoice.accepted#

The receiver accepted the e-invoice.

Scope: Brand · Webhooks: delivered

data.object:

einvoice.delivered#

The e-invoicing provider delivered the e-invoice to the buyer's access point or platform.

Scope: Brand · Webhooks: delivered

data.object:

einvoice.failed#

The e-invoice couldn't be generated or sent, for a reason retrying alone won't fix (error.code, error.message): for example a buyer without an electronic address. Retry it with einvoices.retry once the cause is fixed.

Scope: Brand · Webhooks: delivered

data.object:

einvoice.rejected#

The receiver rejected the e-invoice; error.message gives its reason. The invoice itself stands: correct it with a credit note or fix the buyer's details and retry the e-invoice.

Scope: Brand · Webhooks: delivered

data.object:

einvoice.sent#

An issued invoice's or credit note's e-invoice was generated (EN 16931 UBL, Peppol BIS Billing 3.0) and the entity's e-invoicing provider took it for delivery. status is queued and externalId is the provider's ID.

Scope: Brand · Webhooks: delivered

data.object:

Feature#

feature.created#

A feature (an entitlement definition such as seats.max) was created for the brand.

Scope: Brand · Webhooks: delivered

data.object:

feature.updated#

A feature's name, combine rule, default value or enum values changed. previous_attributes has the old values.

Scope: Brand · Webhooks: delivered

data.object:

Filing period#

filing_period.created#

A filing period was created for a regime the entity is registered in (or in a grace period for), from the regime's filing rules: its dates and due date.

Scope: Legal entity · Webhooks: delivered

data.object:

filing_period.due_soon#

A return is due in 14, 7 or 2 days and isn't filed yet (reminder is the alert code, daysBefore the days left).

Scope: Legal entity · Webhooks: delivered

data.object:

filing_period.locked#

A filing period that is over was locked, ready for its report.

Scope: Legal entity · Webhooks: delivered

data.object:

filing_period.paid#

The tax of the period was paid: the payment reference is recorded and the ledger moved the tax payable to the bank.

Scope: Legal entity · Webhooks: delivered

data.object:

filing_period.prepared#

The period's report was generated (again) and it reconciles with the ledger: the report files and totals are on the period.

Scope: Legal entity · Webhooks: delivered

data.object:

filing_period.ready#

A filing period is over and its return isn't filed yet: it can now be locked and its report prepared. Once per period, when its lock date (lockableAt) has passed.

Scope: Legal entity · Webhooks: delivered

data.object:

filing_period.submitted#

The return was filed with the tax authority; the period has its reference.

Scope: Legal entity · Webhooks: delivered

data.object:

Invitation#

invitation.created#

Someone was invited to the organization. The invitation email is a separate effect; the event never contains the invitation token.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

invitation.revoked#

A pending invitation was revoked. Its link stops working immediately.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

Invoice#

invoice.finalized#

A draft invoice was finalized: it got its number and a fresh tax quote, and the customer's credit balance was applied. status is open (amount due in amountDue), or paid when the credit balance covered it. invoice.issued is emitted with it.

Scope: Brand · Webhooks: delivered

data.object:

invoice.issued#

An invoice or receipt was issued: numbered without gaps in the brand's series and its content fixed (a paid checkout, or a finalized draft). data is the invoice (invoices.get); its PDF is rendered right after (pdf.status turns ready). A pending_registration invoice was charged before a registration number existed: the receipt goes out now, the formal invoice once the number exists.

Scope: Brand · Webhooks: delivered

data.object:

invoice.overdue#

An open send_invoice invoice is overdue: its due date plus the brand's grace days have passed. A subscription invoice also puts the subscription in past_due.

Scope: Brand · Webhooks: delivered

data.object:

invoice.paid#

An invoice was paid in full: marked paid with the bank transfer's date and reference, paid by card, or covered by the customer's credit balance at finalization. payment says how.

Scope: Brand · Webhooks: delivered

data.object:

invoice.payment_failed#

A charge of an open invoice was declined: the first charge, a dunning retry, or the retry after a payment-method update. The invoice stays open; payment.failed has the declined payment.

Scope: Brand · Webhooks: delivered

data.object:

invoice.upcoming#

A subscription renews in 7 days: data is the invoice the renewal will issue as known now (licensed items in advance, metered usage so far, pending items, discounts, tax at today's rates), without a number. Add invoice items or warn the customer now.

Scope: Brand · Webhooks: delivered

data.object:

invoice.voided#

A draft or an open invoice was voided. A voided open invoice keeps its number (numbers are never reused) and its ledger posting is reversed, including credit balance it used; a voided draft never had a number.

Scope: Brand · Webhooks: delivered

data.object:

Lease#

lease.expired#

A lease reached its TTL without a closing settle and its expiry policy was applied: release returned the remaining funds to the wallet, capture charged them, and hold_for_late_settle keeps them reserved until data.lateSettleUntil (status expired_pending). Sent once per lease.

Scope: Brand · Webhooks: delivered

data.object:

Legal entity#

legal_entity.created#

A legal entity (seller of record) was added to the organization. It starts unverified and onboarding.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

legal_entity.updated#

A legal entity's details changed. previous_attributes has the old values.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

Membership#

membership.removed#

A member was removed from the organization (or from one entity or brand).

Scope: Organization · Webhooks: not delivered (internal)

data.object:

membership.updated#

A member's role, scope or live-mode access changed. previous_attributes has the old values.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

Organization#

organization.closed#

The organization is closed: read-only and still exportable. Personal data not needed for financial records was pseudonymised.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.closing#

An owner started closing the organization: live checkouts stop and its subscriptions are being cancelled. It closes once open invoices, refunds and the final filing periods are done.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.created#

An organization was created. Ownrecord then creates its billing account on the platform brand, starts it on the free sandbox plan, and emails the person who created it the welcome with the next steps.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.export_failed#

The organization export couldn't be built; failure says why. Request it again.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.export_ready#

The organization export (a ZIP of JSON files and PDFs) is ready to download for 7 days.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.export_requested#

An export of the whole organization was requested (internal); the organization_export job builds it.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.onboarding_updated#

Someone skipped, resumed or confirmed an onboarding step. data is the checklist with every step's state.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.ownership_offer_cancelled#

An open offer of ownership was cancelled before it was accepted.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.ownership_offered#

An owner offered ownership of the organization to another member, who has 7 days to accept. They were emailed.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.plan_updated#

The organization's Ownrecord plan changed: its subscription, status, period end or entitlements (spec §37.4). previous_attributes.plan has the old values.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.reactivated#

A restricted or suspended organization is active again: its open Ownrecord invoices were paid, a platform admin held the escalation, or a platform admin lifted a suspension for abuse of an organization that is paid up.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.reinstated#

A platform admin lifted the organization's suspension for abuse. Its status is what its Ownrecord subscription says: active when paid, otherwise the stage that is due for how long it has been unpaid. previous_attributes.status is suspended.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.restricted#

The organization's Ownrecord subscription has been unpaid for 14 days (by default): nothing new can be created in live mode until it is paid. Existing checkouts, renewals and webhooks keep running.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.suspended#

The organization's Ownrecord subscription has been unpaid for 30 days (by default): new live checkouts are refused. Renewals, refunds, the customer portal and filings continue.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

organization.updated#

The organization's name or slug changed. previous_attributes has the old values. A slug change moves the console URLs.

Scope: Organization · Webhooks: not delivered (internal)

data.object:

Payment#

payment.failed#

A payment attempt failed at the processor (for example, the card was declined). The checkout stays open, so the customer can try another payment method. data is the failed attempt.

Scope: Brand · Webhooks: delivered

data.object:

payment.succeeded#

A payment succeeded and was recorded with its checkout session, ledger transactions and invoice. data is the payment.

Scope: Brand · Webhooks: delivered

data.object:

Payment method#

payment_method.attached#

A payment method was saved for a customer (a subscription checkout or a setup checkout), for off-session charges.

Scope: Brand · Webhooks: delivered

data.object:

payment_method.detached#

A payment method was removed from a customer; it is no longer charged.

Scope: Brand · Webhooks: delivered

data.object:

payment_method.updated#

A payment method became (or stopped being) the customer's default. previous_attributes.isDefault has the old value.

Scope: Brand · Webhooks: delivered

data.object:

Payout#

payout.failed#

A processor payout came back to the processor balance: the payout posting was reversed.

Scope: Legal entity · Webhooks: delivered

data.object:

payout.paid#

A processor payout reached the legal entity's bank: Dr bank / Cr processor clearing is in the ledger.

Scope: Legal entity · Webhooks: delivered

data.object:

Price#

price.created#

A price was created for one of the brand's products.

Scope: Brand · Webhooks: delivered

data.object:

price.updated#

A price changed: its nickname, lookup key (set, removed or moved to another price), metadata, active, or, while unused, its amounts. previous_attributes has the old values.

Scope: Brand · Webhooks: delivered

data.object:

Processor connection#

processor_connection.created#

A processor was connected to a legal entity: the key was tested and stored encrypted, and the webhook endpoint was set up.

Scope: Legal entity · Webhooks: not delivered (internal)

data.object:

processor_connection.disconnected#

A processor connection was disconnected: its API key was destroyed and it can't be used for payments any more.

Scope: Legal entity · Webhooks: not delivered (internal)

data.object:

processor_connection.updated#

A processor connection changed: its key was rotated, its label changed, or it was marked degraded or active. previous_attributes has the old status, label or key hint.

Scope: Legal entity · Webhooks: not delivered (internal)

data.object:

Product#

product.created#

A product was created in the brand's catalog.

Scope: Brand · Webhooks: delivered

data.object:

product.updated#

A product changed: its name, description, tax category, kind, entitlements, images, metadata or active (archived or reactivated). previous_attributes has the old values.

Scope: Brand · Webhooks: delivered

data.object:

Promotion code#

promotion_code.created#

A customer-facing promotion code was created for one of the brand's coupons.

Scope: Brand · Webhooks: delivered

data.object:

promotion_code.updated#

A promotion code's metadata or active changed (archived or reactivated). previous_attributes has the old values.

Scope: Brand · Webhooks: delivered

data.object:

Rate#

rate.changed#

A tax rate the entity charges changed: a knowledge base update added, changed or retired a rate this mode uses, in a jurisdiction where one of the entity's registrations is registered or in grace. changes lists them with the regimes concerned; a future validFrom takes effect on that date.

Scope: Legal entity · Webhooks: delivered

data.object:

Reconciliation#

reconciliation.item.ignored#

A person took an open reconciliation item out of the queue, with a note; nothing was posted.

Scope: Legal entity · Webhooks: delivered

data.object:

reconciliation.item.resolved#

A person resolved an open reconciliation item, with a note (and for a bank line, the payout it confirms).

Scope: Legal entity · Webhooks: delivered

data.object:

reconciliation.run.completed#

A reconciliation run of a processor connection finished: the balance transactions it read, matched and queued, and the fees and payouts it posted.

Scope: Legal entity · Webhooks: delivered

data.object:

reconciliation.run.requested#

A person or agent asked for a reconciliation run of one processor connection now (internal).

Scope: Legal entity · Webhooks: not delivered (internal)

data.object:

Refund#

refund.failed#

The processor refused or failed a refund. The credit note stands and the amount stays owed to the customer (refunds_payable) until an operator resolves it; the REFUND_FAILED alert says so. data.failure has the processor's code.

Scope: Brand · Webhooks: delivered

data.object:

refund.succeeded#

The processor confirmed a refund: the money is on its way back to the customer. data is the refund (refunds.get) with processorRefundRef.

Scope: Brand · Webhooks: delivered

data.object:

Registration#

registration.deadline_escalated#

The grace deadline came closer and an escalation alert was raised: half or 80% of the time to register has passed, or a daily reminder in the last three days before new consumer sales stop automatically. previous_attributes.escalationLevel is the level before.

Scope: Legal entity · Webhooks: delivered

data.object:

registration.state_changed#

A registration's state, its reason or armed changed: an operator armed it, marked the application submitted, marked it registered or deregistered it; a sale crossed a threshold (grace or blocked); the deadline passed (automatic block); or the counters reached the pre-registration level. previous_attributes has the old state, stateReason and armed.

Scope: Legal entity · Webhooks: delivered

data.object:

registration.updated#

A registration changed without a state change, e.g. a prerequisite's status, notes, owner or attachments.

Scope: Legal entity · Webhooks: delivered

data.object:

Reservation#

reservation.expired#

A single reservation reached its expiresAt without being captured or released: the reservation_expiry job released its funds back to the wallet. data is the reservation as reservations.get returns it.

Scope: Brand · Webhooks: delivered

data.object: