Webhook Alignment Guide

This page details the Frisbii Transform Webhook events and provides the corresponding Frisbii Billing Webhook Event that should be used post-migration.

A full list of Frisbii Billing Webhook events can be found here: docs.frisbii.com/reference/event

Quick reference

Transform	Billing
AccountCreated	—
PaymentSucceeded	invoice_settled
PaymentFailed	invoice_failed
ContractChanged	subscription_changed
DebitAuthCancelled	invoice_cancelled / customer_payment_method_deleted
CustomerChanged	customer_changed
PaymentEscalated	invoice_dunning / invoice_dunning_notification
PaymentBearerExpiring	—
RecurringBillingApproaching	—
InvoiceCreated	invoice_created
PaymentRegistered	invoice_authorized / invoice_settled
DunningCreated	invoice_dunning / invoice_dunning_notification
PaymentProcessStatusChanged	invoice_settled / invoice_failed / invoice_changed
TrialEndApproaching	—
ContractCancelled	subscription_cancelled
OrderSucceeded	subscription_created / invoice_settled
PaymentDataChanged	subscription_payment_method_changed / customer_payment_method_updated
PaymentEscalationReset	invoice_dunning_cancelled
PaymentBearerExpired	customer_payment_method_failed
InvoiceCorrected	invoice_changed / invoice_credited
ContractCreated	subscription_created
CustomerDeleted	customer_deleted
CustomerCreated	customer_created
ReportSucceeded / ReportFailed	—
AcctExportSucceeded / AcctExportFailed	—
CustomerLocked / CustomerUnlocked	—
AccountingExportFileCreated	—
PlanCreated / PlanChanged / PlanDeleted	—
PlanVariantCreated / PlanVariantChanged / PlanVariantDeleted	—
ComponentCreated / ComponentChanged / ComponentDeleted	—
InsufficientBalanceForNextBilling	invoice_failed / subscription_on_hold_dunning
AutomaticDowngradeInsufficientBalance	subscription_changed
ContractDataChanged	subscription_changed / customer_changed
ContractDeleted	subscription_expired / subscription_cancelled
PaymentsExportFileCreated	—
ContractWrittenOff	invoice_credited / invoice_cancelled
PaymentDebtCollectionStatusChanged	invoice_dunning_*
PaymentStatusChanged	invoice_settled / invoice_failed / invoice_authorized / invoice_changed

`—` = no Billing webhook equivalent; see Section 2 and full table below.

Event mapping table

Transform event	Billing event(s)	Notes
AccountCreated	—	No Billing equivalent (account/tenant level). Handle in app or ignore.
PaymentSucceeded	invoice_settled	Billing ties payment success to invoice settlement.
PaymentFailed	invoice_failed	Failed payment; may later be authorized, settled, or cancelled.
ContractChanged	subscription_changed	Plan/scheduling/pricing change.
DebitAuthCancelled	invoice_cancelled or customer_payment_method_deleted	Depends whether it’s invoice or payment-method level.
CustomerChanged	customer_changed	Customer information updated.
PaymentEscalated	invoice_dunning or invoice_dunning_notification	Dunning process started or notification step.
PaymentBearerExpiring	—	No direct event. Use Billing payment method APIs or customer portal to track expiry.
RecurringBillingApproaching	—	No direct event. Use subscription_renewal after the fact or subscription/next period APIs.
InvoiceCreated	invoice_created	Invoice created.
PaymentRegistered	invoice_authorized or invoice_settled	Payment recorded; map to authorized or settled as appropriate.
DunningCreated	invoice_dunning or invoice_dunning_notification	Dunning state entered or notification due.
PaymentProcessStatusChanged	invoice_settled, invoice_failed, or invoice_changed	Map by outcome (success/fail/other).
TrialEndApproaching	—	No direct event. Use subscription_trial_end when trial actually ends.
ContractCancelled	subscription_cancelled	Subscription set to cancel at period end.
OrderSucceeded	subscription_created and/or invoice_settled	New subscription created and/or first invoice settled.
PaymentDataChanged	subscription_payment_method_changed or customer_payment_method_updated	Subscription vs customer-level.
PaymentEscalationReset	invoice_dunning_cancelled	Dunning cancelled (e.g. after payment).
PaymentBearerExpired	customer_payment_method_failed or handle in app	No “expired” event; failed/inactive PM is closest.
InvoiceCorrected	invoice_changed or invoice_credited	Non-state attribute change or credit note/credit.
ContractCreated	subscription_created	Subscription created.
CustomerDeleted	customer_deleted	Customer deleted.
CustomerCreated	customer_created	Customer created.
ReportSucceeded	—	No Billing equivalent (reporting is out of scope for Billing webhooks).
ReportFailed	—	No Billing equivalent.
AcctExportSucceeded	—	No Billing equivalent (accounting export).
AcctExportFailed	—	No Billing equivalent.
CustomerLocked	—	No direct event. Treat as customer_changed if you store lock state in metadata.
CustomerUnlocked	—	No direct event. Same as above.
AccountingExportFileCreated	—	No Billing equivalent.
PlanCreated	—	No Billing equivalent (catalogue; no plan webhooks).
PlanChanged	—	No Billing equivalent.
PlanDeleted	—	No Billing equivalent.
PlanVariantCreated	—	No Billing equivalent.
PlanVariantChanged	—	No Billing equivalent.
PlanVariantDeleted	—	No Billing equivalent.
ComponentCreated	—	No Billing equivalent (add-on catalogue; no webhooks).
ComponentChanged	—	No Billing equivalent.
ComponentDeleted	—	No Billing equivalent.
InsufficientBalanceForNextBilling	invoice_failed or subscription_on_hold_dunning	Payment failure or subscription put on hold due to dunning.
AutomaticDowngradeInsufficientBalance	subscription_changed	Plan/price change; may include downgrade.
ContractDataChanged	subscription_changed or customer_changed	Depends on what data changed.
ContractDeleted	subscription_expired or subscription_cancelled	Contract removed / subscription ended.
PaymentsExportFileCreated	—	No Billing equivalent.
ContractWrittenOff	invoice_credited or invoice_cancelled	Write-off often reflected as credit or cancelled invoice.
PaymentDebtCollectionStatusChanged	invoice_dunning_* or handle in app	Map to dunning events if applicable.
PaymentStatusChanged	invoice_settled, invoice_failed, invoice_authorized, or invoice_changed	Map by new status.

Transform events with no Billing webhook equivalent

These Transform events have no direct Billing event. Handle in migration logic or application code, or accept that the trigger will not exist in Billing.

Transform event	Suggestion
AccountCreated	Ignore or handle in app (tenant/account level).
PaymentBearerExpiring	Poll payment method or use Billing APIs; no expiry webhook.
RecurringBillingApproaching	Use APIs for next renewal; use subscription_renewal after the fact.
TrialEndApproaching	Use subscription_trial_end when trial ends.
ReportSucceeded / ReportFailed	Reporting is out of scope for Billing webhooks.
AcctExportSucceeded / AcctExportFailed	Accounting export is out of scope.
CustomerLocked / CustomerUnlocked	Use customer_changed + metadata if you need lock state.
AccountingExportFileCreated	No equivalent.
PlanCreated / PlanChanged / PlanDeleted	Catalogue; no plan webhooks in Billing.
PlanVariantCreated / PlanVariantChanged / PlanVariantDeleted	Same as above.
ComponentCreated / ComponentChanged / ComponentDeleted	Add-on catalogue; no webhooks.
PaymentsExportFileCreated	No equivalent.

Billing events with no Transform event (or different name)

Use these when registering new webhooks in Billing so you don’t miss behaviour you care about.

Billing event	Transform equivalent / note
invoice_authorized	PaymentRegistered / payment authorized.
invoice_dunning	PaymentEscalated, DunningCreated.
invoice_dunning_notification	DunningCreated, PaymentEscalated.
invoice_dunning_cancelled	PaymentEscalationReset.
invoice_refund	No direct Transform event in your list; map from refund APIs.
invoice_refund_failed	No direct Transform event.
invoice_reactivate	Reactivation of failed/cancelled invoice.
invoice_changed	InvoiceCorrected, or other non-state changes.
invoice_credited	InvoiceCorrected, ContractWrittenOff.
invoice_dispute_*	No direct Transform event; Billing-specific.
subscription_payment_method_added	PaymentDataChanged (first PM).
subscription_payment_method_changed	PaymentDataChanged.
subscription_trial_end	TrialEndApproaching (after the fact).
subscription_renewal	RecurringBillingApproaching (after the fact).
subscription_uncancelled	No direct Transform event.
subscription_on_hold	Contract paused (e.g. ContractChanged).
subscription_on_hold_dunning	InsufficientBalanceForNextBilling / dunning.
subscription_reactivated	Contract resumed.
subscription_expired	ContractDeleted / contract ended.
subscription_expired_dunning	Subscription expired due to dunning.
customer_payment_method_added	PaymentDataChanged.
customer_payment_method_failed	PaymentBearerExpired, PaymentFailed.
customer_payment_method_updated	PaymentDataChanged.
customer_payment_method_reactivated	Card retried and active again.
customer_payment_method_deleted	PaymentDataChanged / DebitAuthCancelled.
payout_created / payout_paid / payout_failed	No Transform equivalent; Billing payout lifecycle.

Implementation notes

1. Re-register all webhooks in Billing; event names and payloads differ from Transform. Use the Billing Webhook reference and Event reference for URLs and payload shapes.

2. Signature verification: Billing uses HMAC-SHA256 with a shared secret. Verify the X-Frisbii-Signature (or current header name in docs) on every webhook request.

3. Payload shape: Transform and Billing use different resource identifiers (e.g. integer IDs vs string handles). Update handlers to use Billing handles and resource links.

4. Catalogue and exports: Plan, plan variant, component, and export events have no Billing webhook equivalent; replace with polling or API-driven flows where needed.