Copy page

Products

Webhooks

Register HTTPS endpoints to receive signed event notifications. Manage endpoints under Marketplace → Webhooks in the LedgerBee app, or via the API — the Webhook Endpoints tag in the API Reference (create, list, update, delete, roll-secret, and a test delivery; scopes webhook-endpoints-read / webhook-endpoints-write).

Endpoint URLs must be public HTTPS — plain http and private/loopback hosts are rejected at creation. Creating an endpoint returns a signing secret of the form whsec_…, shown once; store it to verify every delivery.

Delivery envelope

Every delivery POSTs a JSON envelope — and the whole envelope is what gets signed:

Code
{
  "id": "…",          // the delivery id — same value as the webhook-id header
  "type": "subscription.started",
  "timestamp": "2026-06-01T12:00:00.000Z",
  "data": { … }       // topic-specific payload
}

Signing — Standard Webhooks

Every delivery is signed following the Standard Webhooks specification. Each request carries three headers:

• webhook-id — unique message id; matches id in the body
• webhook-timestamp — send time in unix seconds (use it for a replay window; reject timestamps far outside your clock)
• webhook-signature — v1,<base64 HMAC-SHA256> over {id}.{timestamp}.{rawBody} (space-separated entries; verify against each)

Verifying a delivery

Do not hand-roll the HMAC check. Use one of the Standard Webhooks drop-in libraries with the endpoint secret (returned once when you create the endpoint or roll its secret). Verify against the raw request body — don't re-serialize the parsed JSON; whitespace changes break the HMAC:

Code
import { Webhook } from 'standardwebhooks';

const wh = new Webhook(endpointSecret); // "whsec_..." from create/roll-secret

app.post('/ledgerbee-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body, req.headers); // throws on bad signature / stale timestamp
  } catch {
    return res.sendStatus(400); // reject unverified payloads — do not process them
  }
  handle(event); // event === the parsed { id, type, timestamp, data }
  res.sendStatus(200);
});

Retries

A non-2xx response or a timeout is retried up to 8 total attempts over roughly 21 hours, with exponential backoff (30s → 2m → 8m → 32m → ~2h → ~8.5h → 10h). Every retry carries the same webhook-id — but is re-signed with the new send time, so verify against the headers of the delivery you received, and deduplicate on webhook-id. Deliveries can arrive out of order. After the schedule is exhausted the delivery is marked failed in the endpoint's delivery log (Marketplace → Webhooks).

Reconciling subscription events

Every subscription.* event's data carries partnerReferenceId — the clientReferenceId passed when binding an embedded checkout. It's your join key: match the event to your own order without storing LedgerBee ids first. If a delivery is missed (endpoint down, not yet subscribed), recover over the API instead of replaying: GET /v1/subscriptions?partnerReferenceId=<yours> — see Subscriptions.

Access-boundary subscription events carry entitlementIds so consumers can apply the current product-entitlement union without a second lookup. Paused and churned events carry an empty array for deterministic revocation. See Product Entitlements for the grant and revoke contract.

Best practices

• Verify the signature before trusting the payload.
• Return 2xx quickly; do heavy work asynchronously. The response body is ignored.
• Expect retries and rare duplicates — make handling idempotent on webhook-id.
• Store the secret securely; roll it from Marketplace → Webhooks if exposed (deliveries re-sign with the new secret immediately).
• Use the test delivery (UI button or POST /v1/webhook-endpoints/{id}/test) to wire up verification before real traffic arrives.

Event types

Subscribe an endpoint to any of the topics below. Each delivery carries the topic string in the envelope type field and the topic-specific payload in data — see the delivery envelope for the wrapper.

Subscription

subscription.assigned

Fired when a subscription is assigned to a customer (may be future-dated / upcoming).

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer the subscription was assigned to.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
entitlementIds	string (uuid)[]	The full entitlement id set granted as of this event. An empty array means no access; consumers should re-sync instead of applying a diff.
assignedAt	string (date-time)	ISO 8601 timestamp of when the subscription was assigned.

subscription.started

Fired when a subscription becomes active — grant entitlement/access on this event, not on assigned.

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer that owns the subscription.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
entitlementIds	string (uuid)[]	The full entitlement id set granted as of this event. An empty array means no access; consumers should re-sync instead of applying a diff.
startedAt	string (date-time)	ISO 8601 timestamp of when the subscription became active.

subscription.updated

Fired when a config property changes without a structural transition (e.g. name, payment method, billing direction).

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer that owns the subscription.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
changedFields	string[]	Names of the subscription fields changed in this update.
updatedAt	string (date-time)	ISO 8601 timestamp of when the update was applied.

subscription.transitioned

Fired on a structural change: plan replace, product edit, billing cadence change, phase change, or realign.

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer that owns the subscription.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
entitlementIds	string (uuid)[]	The full entitlement id set granted as of this event. An empty array means no access; consumers should re-sync instead of applying a diff.
transitionType	plan_replaced | products_edited | billing_cadence_changed | billing_realigned | phase_changed	Which kind of structural change occurred.
transitionedAt	string (date-time)	ISO 8601 timestamp of when the transition was applied.

subscription.paused

Fired when a subscription is paused.

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer that owns the subscription.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
entitlementIds	string (uuid)[]	The full entitlement id set granted as of this event. An empty array means no access; consumers should re-sync instead of applying a diff.
pausedAt	string (date-time)	ISO 8601 timestamp of when the subscription was paused.

subscription.resumed

Fired when a subscription resumes from a pause.

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer that owns the subscription.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
entitlementIds	string (uuid)[]	The full entitlement id set granted as of this event. An empty array means no access; consumers should re-sync instead of applying a diff.
resumedAt	string (date-time)	ISO 8601 timestamp of when the subscription resumed.

subscription.trial_ended

Fired when a subscription trial ends. The payload outcome says whether billing begins (ACTIVE) or the subscription was held for a missing payment card (PAUSED).

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer that owns the subscription.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
entitlementIds	string (uuid)[]	The full entitlement id set granted as of this event. An empty array means no access; consumers should re-sync instead of applying a diff.
endedAt	string (date-time)	ISO 8601 timestamp of when the trial ended.
outcome	ACTIVE | PAUSED	Status the subscription landed in when the trial ended: ACTIVE (billing begins) or PAUSED (held until a payment card is added).

subscription.cancellation_scheduled

Fired when a future cancellation is scheduled for a subscription (still active until then).

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer that owns the subscription.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
effectiveDate	string (date-time) or null	When the cancellation takes effect, if known.
scheduledAt	string (date-time)	ISO 8601 timestamp of when the cancellation was scheduled.

subscription.cancellation_cleared

Fired when a previously scheduled cancellation is cleared.

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer that owns the subscription.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
clearedAt	string (date-time)	ISO 8601 timestamp of when the scheduled cancellation was cleared.

subscription.churned

Fired when a subscription is cancelled/finalized — revoke entitlement on this event.

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer that owned the subscription.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
entitlementIds	string (uuid)[]	The full entitlement id set granted as of this event. An empty array means no access; consumers should re-sync instead of applying a diff.
reason	string or null	Free-text cancellation reason, if one was supplied.
churnedAt	string (date-time)	ISO 8601 timestamp of when the subscription was cancelled.
mergedIntoSubscriptionId	string (uuid) or null	Set when this cancellation is one half of a subscription merge: the id of the surviving subscription that carries this subscription’s lines forward. Do NOT revoke entitlements on a merge churn — access continues on the surviving subscription.

subscription.billed

Fired once per subscription that billed onto an invoice — one per child on a parent-paid consolidated invoice, one per member on a billing-group invoice. amount is always the whole document total; deduplicate on invoiceId, attribute on billingGroupId, never sum amount across events.

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer that owns the subscription.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
billingGroupId	string (uuid) or null	Billing group whose shared invoice this event reports, or null. When set, every member of the group receives its own billed event for the same invoiceId, each carrying the whole document total — deduplicate on invoiceId.
invoiceId	string (uuid)	Id of the invoice produced by the billing run.
invoiceNumber	string	Human-facing invoice number.
amount	string	Total invoice amount of the whole document, as a decimal string — NOT this subscription's share. On a shared invoice every subscription on it reports the same figure.
currency	string	ISO 4217 currency code of the invoice.
usageCommitment	object or null	Prepaid usage-commitment portion of the invoice. Null when the invoice carries no commitment lines.
usageCommitment.committedAmount	string	Sum of the prepaid usage-commitment lines on this invoice, as a decimal string. Present only when usageCommitment is non-null.
usageCommitment.trueUpAmount	string	Signed sum of the usage true-up (settlement) lines on this invoice, as a decimal string. Positive = overage billed, negative = underage refunded. Present only when usageCommitment is non-null.
billedAt	string (date-time)	ISO 8601 timestamp of when the invoice was produced.

subscription.payment_succeeded

Fired when a card charge for the subscription clears — the success pair of the charge_failed error signal. On a billing-group card charge one event fires per member, each carrying the full charged amount and the shared billingGroupId.

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer that owns the subscription.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
billingGroupId	string (uuid) or null	Billing group whose card paid the invoice, or null when the subscription's own card did. When set, every member of the group receives its own payment_succeeded for the same invoiceId — deduplicate on invoiceId.
invoiceId	string (uuid)	Id of the invoice the charge paid.
invoiceNumber	string	Human-facing number of the invoice the charge paid.
amount	string	Charged amount, as a decimal string — the whole invoice, NOT this subscription's share when the invoice is shared.
currency	string	ISO 4217 currency code of the charge.
paidThroughDate	string or null	The date the subscription is now paid through: the exclusive end of the latest service period covered by a settled invoice (equivalently, the first day not yet paid for). Null when no covered period exists, e.g. a one-off-only invoice. This is the paid-through marker — nextBillingDate is NOT: that says when the next invoice is created.
occurredAt	string (date-time)	ISO 8601 timestamp of when the charge cleared.

subscription.error

Fired when a delivery/processing problem occurs for a subscription (e.g. undeliverable recipient).

Field	Type	Description
subscriptionId	string (uuid)	Stable id of the subscription (the chain head id, fixed at creation and unchanged across plan / direction / cadence changes and cancellation). Correlate events to a subscription on this id.
versionId	string (uuid)	Internal version-chain row the event was emitted on. Advanced/debug only — it drifts across changes; correlate on subscriptionId or partnerReferenceId, not this.
customerId	string (uuid)	Id of the customer that owns the subscription.
partnerReferenceId	string or null	Your clientReferenceId from embedded checkout, echoed back for reconciliation. Null when none was set.
errorType	recipient_undeliverable | charge_failed | dunning_exhausted	Which problem occurred — see the subscription.error sub-events table for the full set and meaning.
message	string	Human-readable description of the problem.
occurredAt	string (date-time)	ISO 8601 timestamp of when the problem occurred.

The errorType field discriminates which problem occurred — it is one of:

errorType	Meaning
recipient_undeliverable	A document recipient for the subscription is undeliverable (e.g. the email hard-bounced); the document was not delivered.
charge_failed	A card charge (first or recurring) for the subscription failed. Automatic retries continue across the grace window, and this fires on each decline. The raw provider decline is not exposed on the payload.
dunning_exhausted	Automatic card-charge retries for the subscription are exhausted after the grace window; no further automatic attempts will be made and the outstanding invoice becomes collectible. Fires once per subscription, distinct from the per-decline charge_failed — a billing group emits one per member, each naming that member, so "once per subscription" holds on both rails.

Billing

billing.invoice_sent

Fired when an invoice document is sent to the customer.

Field	Type	Description
invoiceId	string (uuid)	Id of the invoice that was sent.
invoiceNumber	string	Human-facing invoice number.
customerId	string (uuid)	Id of the customer the invoice was sent to.
subscriptionId	string (uuid) or null	Subscription the invoice relates to, or null when the document is not a single subscription's — a billing-group invoice (see billingGroupId), a parent-paid consolidated invoice, or a manually created one.
billingGroupId	string (uuid) or null	Billing group the invoice is issued to, or null. A group's shared invoice names the group and never a subscription, so subscriptionId is null whenever this is set.
amount	string	Total invoice amount, as a decimal string.
currency	string	ISO 4217 currency code of the invoice.
sentAt	string (date-time)	ISO 8601 timestamp of when the invoice was sent.

billing.credit_note_sent

Fired when a credit note document is sent to the customer.

Field	Type	Description
creditNoteId	string (uuid)	Id of the credit note that was sent.
creditNoteNumber	string	Human-facing credit note number.
customerId	string (uuid)	Id of the customer the credit note was sent to.
subscriptionId	string (uuid) or null	Subscription the credit note relates to, or null when the document is not a single subscription's — a billing-group credit note (see billingGroupId), a parent-paid consolidated one, or a manually created one.
billingGroupId	string (uuid) or null	Billing group the credit note is issued to, or null. A group's credit note names the group and never a subscription, so subscriptionId is null whenever this is set.
amount	string	Total credit note amount, as a decimal string.
currency	string	ISO 4217 currency code of the credit note.
sentAt	string (date-time)	ISO 8601 timestamp of when the credit note was sent.

Customer

customer.created

Fired when a customer is created (payload flags whether it was a portal self-signup).

Field	Type	Description
customerId	string (uuid)	Id of the created customer.
selfSignup	boolean	True when the customer was created via portal self-signup; false for operator/API/import creation.
partnerReferenceId	string or null	Your own order/cart id, echoed from the checkout-vouch token that created this customer. Non-null only on a partner-vouched checkout; null for every other creation path. Use it to map the customer back to the order in your system — the same identifier the subscription webhooks carry.
createdAt	string (date-time)	ISO 8601 timestamp of when the customer was created.

Card

card.added

Fired when a card is successfully saved for a customer (provider-opaque).

Field	Type	Description
cardId	string (uuid)	Id of the saved card (LedgerBee CustomerPaymentMethod id).
customerId	string (uuid)	Id of the customer the card was saved for.
cardMask	string or null	Masked card number, if known.
cardType	string or null	Card network/brand, if known — never the payment provider.
expiryMonth	integer or null	Card expiry month (1–12), if known.
expiryYear	integer or null	Card expiry year (4-digit), if known.
isDefault	boolean	True when this card is the customer’s default after being saved.
addedAt	string (date-time)	ISO 8601 timestamp of when the card was saved.

card.removed

Fired when a saved card is removed in-app or cancelled at the provider.

Field	Type	Description
cardId	string (uuid)	Id of the removed card.
customerId	string (uuid)	Id of the customer the card belonged to.
cardMask	string or null	Masked card number, if known.
cardType	string or null	Card network/brand, if known.
reason	removed_by_customer | removed_by_provider	Why the card was removed: removed_by_customer = removed in-app (portal/operator); removed_by_provider = cancelled out-of-band at the provider.
removedAt	string (date-time)	ISO 8601 timestamp of when the card was removed.

card.updated

Fired when a saved card’s details change (network auto-update or refresh).

Field	Type	Description
cardId	string (uuid)	Id of the updated card.
customerId	string (uuid)	Id of the customer that owns the card.
cardMask	string or null	Masked card number after the update, if known.
cardType	string or null	Card network/brand after the update, if known.
expiryMonth	integer or null	Card expiry month (1–12) after the update, if known.
expiryYear	integer or null	Card expiry year (4-digit) after the update, if known.
isDefault	boolean	Whether this card is the customer’s default.
changedFields	string[]	Names of the card fields that changed in this update.
updatedAt	string (date-time)	ISO 8601 timestamp of when the update was applied.

card.expiring

Fired when a saved card is approaching expiry.

Field	Type	Description
cardId	string (uuid)	Id of the expiring card.
customerId	string (uuid)	Id of the customer that owns the card.
cardMask	string or null	Masked card number, if known.
cardType	string or null	Card network/brand, if known.
expiryMonth	integer or null	Card expiry month (1–12), if known.
expiryYear	integer or null	Card expiry year (4-digit), if known.
signaledAt	string (date-time)	ISO 8601 timestamp of when the expiry signal was raised.

card.expired

Fired when a saved card is observed to have expired.

Field	Type	Description
cardId	string (uuid)	Id of the expired card.
customerId	string (uuid)	Id of the customer that owns the card.
cardMask	string or null	Masked card number, if known.
cardType	string or null	Card network/brand, if known.
expiryMonth	integer or null	Card expiry month (1–12), if known.
expiryYear	integer or null	Card expiry year (4-digit), if known.
expiredAt	string (date-time)	ISO 8601 timestamp of when the card was observed expired.

card.default_changed

Fired when the customer’s default card changes (explicit or auto-default).

Field	Type	Description
cardId	string (uuid)	Id of the card that is now the customer’s default.
customerId	string (uuid)	Id of the customer whose default card changed.
previousDefaultCardId	string (uuid) or null	Id of the card that was previously default, or null if the customer had no default before.
changedAt	string (date-time)	ISO 8601 timestamp of when the default changed.

card.backup_changed

Fired when the customer’s designated backup card is set, replaced, or cleared.

Field	Type	Description
cardId	string (uuid) or null	Id of the card that is now the customer’s designated backup, or null when the designation was cleared.
customerId	string (uuid)	Id of the customer whose backup card changed.
previousBackupCardId	string (uuid) or null	Id of the card that was previously the backup, or null if the customer had no backup before.
changedAt	string (date-time)	ISO 8601 timestamp of when the backup designation changed.

card.add_failed

Fired when a card-save attempt fails (decline or authentication failure).

Field	Type	Description
customerId	string (uuid)	Id of the customer the failed card-save was for.
reason	string	Machine/short reason for the failure (decline or authentication failure).
failedAt	string (date-time)	ISO 8601 timestamp of when the card-save attempt failed.

Quote

quote.sent

Fired when a quote is sent to the customer.

Field	Type	Description
quoteId	string (uuid)	Id of the quote that was sent.
quoteNumber	string or null	Human-facing quote number (allocated on send).
customerId	string (uuid)	Id of the customer the quote was sent to.
sentAt	string (date-time)	ISO 8601 timestamp of when the quote was sent.

quote.converted

Fired when a quote is converted into an order confirmation or an invoice.

Field	Type	Description
quoteId	string (uuid)	Id of the quote that was converted.
quoteNumber	string or null	Human-facing quote number.
targetType	invoice | orderConfirmation	What the quote was converted into.
targetId	string (uuid)	Id of the document the conversion produced (an invoice or order confirmation).
customerId	string (uuid)	Id of the customer the documents belong to.
convertedAt	string (date-time)	ISO 8601 timestamp of when the conversion happened.

Order confirmation

order_confirmation.sent

Fired when an order confirmation is sent to the customer.

Field	Type	Description
orderConfirmationId	string (uuid)	Id of the order confirmation that was sent.
orderConfirmationNumber	string or null	Human-facing order confirmation number (allocated on send).
customerId	string (uuid)	Id of the customer the order confirmation was sent to.
sentAt	string (date-time)	ISO 8601 timestamp of when the order confirmation was sent.

order_confirmation.converted

Fired when an order confirmation is converted into an invoice.

Field	Type	Description
orderConfirmationId	string (uuid)	Id of the order confirmation that was converted.
orderConfirmationNumber	string or null	Human-facing order confirmation number.
targetType	invoice	Order confirmations only ever convert into an invoice.
targetId	string (uuid)	Id of the invoice the conversion produced.
customerId	string (uuid)	Id of the customer the documents belong to.
convertedAt	string (date-time)	ISO 8601 timestamp of when the conversion happened.

Project

project.created

Fired when a project is created (payload carries the owned dimension id for correlation with the dimensions API).

Field	Type	Description
projectId	string (uuid)	Id of the created project.
name	string	Project name at creation time.
dimensionId	string (uuid)	Id of the dimension the project owns; usable with the dimensions API.
externalReference	string or null	Partner-supplied external reference, null when not set.
createdAt	string (date-time)	ISO 8601 timestamp of when the project was created.

project.updated

Fired when a project's fields are updated (payload lists the changed field names). Also fires on un-archive.

Field	Type	Description
projectId	string (uuid)	Id of the updated project.
changedFields	string[]	Names of the project fields the update changed.
updatedAt	string (date-time)	ISO 8601 timestamp of the update.

project.archived

Fired when a project is archived (its dimension is deactivated; postings history is preserved).

Field	Type	Description
projectId	string (uuid)	Id of the archived project.
archivedAt	string (date-time)	ISO 8601 timestamp of the archive action.

Checkout

checkout.card_ready

Fired when the buyer's card lands on a checkout session's card window — confirm may proceed. The card-status poll remains authoritative.

Field	Type	Description
sessionId	string	The checkout session id — the same opaque id your backend received from the session mint.
clientReferenceId	string or null	Your own reference from the session mint; null when none was supplied.
planVersionId	string (uuid)	The plan version the session pinned.
planItemId	string (uuid)	The pricing-card item the session pinned.
card	object or null	The captured card to display to the buyer; null when the provider returned no display details.
card.label	string	Ready-to-render card label. Present only when card is non-null.
card.cardType	string or null	Card network/brand, if known — never the payment provider. Present only when card is non-null.
card.cardMask	string or null	Masked card number, if known. Present only when card is non-null.
card.accountIdentifier	string or null	Masked account identifier for non-card methods (e.g. a Link email); null for plain cards. Present only when card is non-null.

checkout.card_failed

Fired when a checkout card window closes without a card (the provider window expired mid-capture) — open a fresh window to retry.

Field	Type	Description
sessionId	string	The checkout session id — the same opaque id your backend received from the session mint.
clientReferenceId	string or null	Your own reference from the session mint; null when none was supplied.
planVersionId	string (uuid)	The plan version the session pinned.
planItemId	string (uuid)	The pricing-card item the session pinned.
reason	WINDOW_EXPIRED	Why the card capture failed. WINDOW_EXPIRED: the provider window lapsed without a card landing.

checkout.session_expired

Fired when a checkout session expires unconsumed — the abandoned-checkout signal.

Field	Type	Description
sessionId	string	The checkout session id — the same opaque id your backend received from the session mint.
clientReferenceId	string or null	Your own reference from the session mint; null when none was supplied.
planVersionId	string (uuid)	The plan version the session pinned.
planItemId	string (uuid)	The pricing-card item the session pinned.