Events Overview¶
Target Audience: Users, Developers, Stakeholders
Introduction¶
This document defines what events can be triggered in the system, which in turn can trigger emails being sent as well as other operations depending on the triggering event and what listeners are available to that event.
Listeners¶
Listed here are some common listeners that could pick up the event.
- Subscription system integration (SSI)
- Export to external subscription systems such as Kayak, Infosoft, CProfit, and more
- Integrate with your own applications, through webhooks and/or the Azure service bus
- Third party e-mail through the Payway email service
- Standard transactional email through Tulo Payway
Events¶
Below you will find all the different events triggered in Tulo Payway. The entities in the payload depends on the event triggered.
| Name | Entities | Description |
|---|---|---|
| account_activated_for_existing_customer | account | When an account is activated |
| account_created_with_password_reset | account, reset_url | When an account is created without password from Adyen API place_order_without_account |
| account_requested_password_reset | account, reset_url, return_url, title_code | When a password reset is requested for an account |
| account_password_reset_complete | account, login_url | When the password reset procedure is completed for an account |
| account_requested_email_change | account, email_change_url | When a e-mail change is requested for an account |
| account_archived | account | When an account is archived |
| account_status_changed | account | When an account's status is updated |
| registered_account_confirmed | account | When an account is verified |
| confirmation_email_requested | account, confirmation_url | When a confirmation email is requested for an account |
| new_account_registered | account, confirmation_url, return_url | When a new account is created |
| new_checkout_account_registered | account, return_url, reset_url | When a new account is created through the Klarna Instant Shopping callback specifically |
| account_requested_verification_email | account | When a verification email is requested for an account |
| account_changed | account | When an account's information is updated |
| payment_success | account, order, payment, user_product, receipt | When a payment is completed |
| payment_failure | account, order, payment | When a payment fails to be completed |
| payment_user_agreement_invalid_state | account, payment_profile, agreement_status | When a customer payment agreement is determined to be invalid |
| order_closed | account, order, payment, user_product, receipt | When a new order is completed |
| order_closed_shareable | account, order, payment, user_product, receipt, sharing_configuration | When a new order is completed, and the subscription can be shared |
| gift_created | gift | When a new gift order is created |
| gift_order_closed | account, gift_order, receipt | When a new gift order is completed |
| payment_campaign_transformed | account, new order, old user_product, new_user_product | When a user product/subscription is transformed from a campaign into a package |
| payment_user_product_renewed | account, user_product, reason | When a user product is renewed |
| user_product_cancelled | account, user_product | When a user product is cancelled |
| payment_user_product_deactivated | account, user_product, reason | When a user product is deactivated. Subscription is terminated |
| payment_user_product_frozen | account, user_product, reason | When a user product fails to renew and is frozen |
| payment_user_product_created | account, order, user_product | When a user product is created. Subscription starts |
| package_sharing_initialized | share | When a user shares his/hers subscription |
| package_sharing_activated | share | When a user accepts a shared subscription |
| package_sharing_reactivated | share | When a shared subscription is reactivated |
| package_sharing_deactivated | share | When the sharer deactivates the shared subscription |
| new_subscription_period | account, payment, order, user_product | When a new subscription period starts. Subscription is renewed |
| user_product_uncancelled | account, user_product | When a user product is reactivated |
| changed_subscription_renewal_date | account, user_product | When the renewal date for a subscription is changed from PAP |
| changed_subscription_start_date | account, user_product | When the start date for a subscription is changed from PAP |
| account_marketing_permission_changed | account | When an account's marketing permission are updated |
| payment_retry | account, order, payment_retry | When a recurring payment fails, indicates that a automatic retry will happen. |
| payment_retry_successful | account, order, payment, payment_retry | When a payment is successfully retried |
| payment_agreement_about_to_expire | account, order, expire_days, expire_date, masked_creditcard | When a customer payment agreement is about to expire. Card |
| package_upgrade | account, old user_product, new_user_product, order | When a subscription is upgraded to a more expensive package |
| package_downgrade | account, old user_product, new_user_product | When a subscription is downgraded to a less expensive package |
| package_change_completed | account, new order | When a subscription transforms due to a previously triggered package_change |
| pending_user_product_activated | account, user_product | When a pending user product is activated and the subscription starts |
| transitioned_to_retention_campaign | account, user_product | When a user accepts a retention campaign |
| new_account_created_from_kis | account, reset_url | When a new account is registered |
| voucher_created | account, order, receipt, voucher, voucher_redeem_url | When a voucher is created through a voucher purchase |
| voucher_redeemed | account, order, voucher | When a a bought voucher is redeemed by a user |
| marketing_permission_added | account, marketing_permission | When a customer accepts a new marketing permission |
| marketing_permission_removed | account, marketing_permission | When a customer rejects a new marketing permission |
| voucher_user_product_created | account, user_product, voucher | When a voucher is redeemed and a user product is created. Subscription starts. |
| voucher_user_product_deactivated | account, user_product, reason | When a user product created from a voucher is deactivated. Subscription ends. |
| pending_subscription_validation_change | account, user_product | When a user is 14 days from no longer being eligible for a product |
| ess_deactivated_user_product | account, user_product | When a subscription from the External Subscription system is deactivated in Payway due to a sync of subscriptions |
| ess_activated_user_product | account, user_product | When a subscription from the External Subscription system is activated in Payway due to a sync of subscriptions |
| ess_updated_user_product | account, user_product | When a subscription from the External Subscription system is updated in Payway due to a sync of subscriptions |
| ess_changed_provision_service | account, old user_product, new_user_product | When the External Subscription system takes control over payments for a Tulo Provisioned subscription due to a sync of subscriptions |
| ess_changed_package | account, old user_product, new_user_product | When a subscription from the External Subscription system changes package in Payway due to a sync of subscriptions |
| account_requested_one_time_password | account, login_url, valid_until , one_time_password | When a one time password is requested for an account |
| verification_failure | account, order, payment | When a payment cannot be verified. When a card update fails for example |
| campaign_created | product | When a campaign is created, and campaign exports have been enabled. Only available for External subscription systems. |
| campaign_updated | product | When a campaign is updated, and campaign exports have been enabled. Only available for External subscription systems. |
| offline_payment_paid | account, order, payment, receipt | When an offline payment is completed. Only available for External subscription systems. |
| offline_payment_credited | account, order, payment | When an offline payment is credited. Only available for External subscription systems. |
| package_change_completed | account, new order | When a subscription transforms due to a previously triggered package_change. Only available for External subscription systems. |
| package_downgrade_completed | account, new order | When a subscription downgrade transforms to the downgraded subscription. Only available for External subscription systems. |
| payment_profile_update | account, order, payment | When a payment profile is updated. Customer updates card details for example. Only available as a Tulo Payway transactional email. |
| package_change | account, user_product | When a subscription is changed to a different package |
| payment_initiated | account, order, payment | When a payment is initiated but not completed |
Webhooks¶
Webhooks are delivered as POST requests in a standardized payload format. Depending on the event different entities
will be populated in the payload.
{
"event": "<event_name>",
"options": {
"silent_operation": false
},
"timestamp": "2024-06-11T09:14:45.841Z",
"payload": {
"account": {},
"order": {},
"payment": {},
"receipt": {},
"share": {},
"user_product": {},
"new_user_product": {},
"gift": {},
"product": {},
"payment_retry": {},
"event_data": {},
"payment_about_to_expire": {},
"voucher": {},
"marketing_permission": {}
}
}
Options¶
The options object available in the event payload is a collection of optional flags that your system may, or may not want to listen to, depending on what the purpose of your listeners are.
Below you will find a visualisation of what each flag means.
| Key | Description |
|---|---|
| silent_operation | The account has silenced email notifications, and no email communication should currently be done towards the customer. |
Contact¶
To get started, please contact us.