1. Home
  2. Documentation
  3. Marketing Automation
  4. Events & Webhooks

Events & Webhooks

Events & webhooks allow you to perform some behind-the-scenes magic to automate your marketing efforts. Once you start using webhooks to automate email marketing you will get hooked.

What Is An Event?

An event is any action taken by someone inside your plugin/theme.
You have control over what that action will be, and you can pick the user actions you’d like to use out of a list of actions Freemius currently supports for all plugins and themes.
We have found the actions on this list to be the most useful ones to use, but due to customer demand we plan to turn it into an open list, so that you will be able to add any action you want to it. That way, in case you think of an action that is not on the list, but may be very useful for your product to use – you can simply add and use it.

What Is A Webhook?

A webhook is a very useful way to implement a reaction to an event, in real time. It can provide data about an action to the Freemius API, which will, in turn, trigger another action. In the case of Freemius that action will be to send out an email to the user who performed the defined action.

How Can I Use Webhooks?

Let’s use an example where you want to use the Freemius webhooks mechanism to decrease the abandonment rate of your product.
You can leverage it as a trigger to automatically send an email to any user who deactivates your plugin/theme.
In the email you can to ask your user if he/she are having any issues with your product and offer assistance.

For now, the emails are not customizable. We are working on a templates engine that would probably use Twig for email customization.

You can customize the ‘From’ email addresses of the email messages sent by Freemius on your behalf.

How to Test Event’s Payload?

If you’d like to understand the payload of a specified event.type follow these steps:
1. Head to the EVENTS LOG section in the dashboard.
2. Filter the events based on that event.type.
3. Copy the ID of the 1st event shown in the filtered view.
4. Leverage the API to fetch the event’s data:
$fs_event = $fs->Api("/events/{$eventID}.json");
5. The result’s schema from the API is identical to the payload’s schema you’ll get by the webhook once event.type will be processed.

Types of Events

This is a list of all the types of events we currently send. We may add more at any time, so you shouldn’t rely on only these types existing in your code.

You’ll notice that these events follow a pattern: resource.event. Our goal is to design a consistent system that makes things easier to anticipate and code against. NOTE: Events that occur on “sub” resources like developer.billing do not trigger the parent’s update event.

Event
addon.free.downloaded Occurs whenever a free version of an add-on is downloaded.
addon.premium.downloaded Occurs whenever a premium version of an add-on is downloaded.
affiliate.approved Occurs whenever an affiliate is approved.
affiliate.blocked Occurs whenever an affiliate is blocked.
affiliate.created Occurs whenever an affiliate is created.
affiliate.deleted Occurs whenever an affiliate is deleted.
affiliate.paypal.updated Occurs whenever there’s an update of an affiliates PayPal details.
affiliate.rejected Occurs whenever an affiliate is rejected.
affiliate.suspended Occurs whenever an affiliate is suspended.
affiliate.unapproved Occurs whenever an affiliate state is changed from `approved` to `pending`.
affiliate.updated Occurs whenever there’s an update of an affiliate details.
card.created Occurs whenever a new card is added to a user’s dashboard account.
card.updated Occurs whenever a user’s card details have been updated.
cart.abandoned Occurs whenever a cart session has been abandoned.
cart.completed Occurs whenever a ‘sale’ has been completed, but the payment hasn’t necessarily been completed yet (e.g. for trials, 100% coupon codes, or for PayPal subscription which takes 24 to process).
cart.created Occurs whenever a cart session has been initiated.
cart.recovered Occurs whenever an abandoned cart session has been recovered and converted into a ‘sale’ (i.e. triggers the cart.completed event).
cart.recovery.deactivated Occurs when the cart recovery feature has been deactivated in the Developer Dashboard.
cart.recovery.email_1_sent Occurs when the first cart recovery email has been sent.
cart.recovery.email_2_sent Occurs when the second cart recovery email has been sent.
cart.recovery.email_3_sent Occurs when the third (and final) cart recovery email has been sent.
cart.recovery.reactivated Occurs when the cart recovery feature has been reactivated in the Developer Dashboard.
cart.recovery.subscribed Occurs when the prospect re-subscribes to the cart abandonment recovery campaign through a link in the cart recovery emails. Or, if a developer of the product reactivates a recovery campaign through the Developer Dashboard.
cart.recovery.unsubscribed Occurs when the prospect unsubscribes from the cart abandonment recovery campaign through a link in the cart recovery emails. Or, if a developer of the product stops a recovery campaign through the Developer Dashboard.
cart.updated Occurs when the cart contents have been updated.
coupon.created Occurs whenever a coupon is created.
coupon.deleted Occurs whenever a coupon is deleted.
coupon.updated Occurs whenever a coupon is updated.
developer.billing.updated Occurs whenever the billing information of the developer is updated.
developer.secret_key.updated Occurs when the developer secret key has been updated in the Developer Dashboard.
email.clicked Occurs when a link is clicked by a user. Email link click tracking is only included in cart abandonment recovery and trial-related emails.
email.opened Occurs when an email has been opened by a user. Email open tracking is only included in cart abandonment recovery, trial-related, and subscription renewal reminder emails.
install.activated Occurs whenever a user is opted-in, and after reactivation of a product.
install.deactivated Occurs whenever the plugin is deactivated.
install.deleted Occurs whenever a user delete the installation account.
install.connected Occurs whenever a user opts in for sharing basic website info after previously opting out from it.

Important: Starting from Jan 1, 2023, the event name is changing to install.site.opt_in.

install.disconnected Occurs whenever a user opts out from sharing basic website info after previously sharing it.

Important: Starting from Jan 1, 2023, the event name is changing to install.site.opt_out.

install.extensions.opt_in Occurs whenever a user opts in for sharing a website’s plugins & themes list after previously opting out from it.
install.extensions.opt_out Occurs whenever a user opt-out from sharing a website’s plugins & themes list after previously sharing it.
install.installed Occurs whenever a user is opted-in (triggered before install.activated).
install.language.updated Occurs whenever an installation language is updated.
install.ownership.candidate.confirmed Occurs whenever an account ownership transfer candidate confirms the transfer.
install.ownership.completed Occurs whenever an account ownership transfer is complete.
install.ownership.initiated Occurs whenever an account ownership transfer is initiated.
install.ownership.owner.confirmed Occurs whenever an account ownership transfer is confirmed by the current installation account owner.
install.plan.changed Occurs whenever an installation plan is changed.
install.plan.downgraded Occurs whenever an installation plan is downgraded to the default plan (if the default plan is free, then when downgraded back to the free version).
install.platform.version.updated Occurs whenever an installation WordPress version is updated.
install.premium.activated Occurs whenever the premium code version of the plugin is activated.
install.premium.deactivated Occurs whenever the premium code version of the plugin is deactivated.
install.programming_language.version.updated Occurs whenever an installation PHP version is updated.
install.site.opt_in Occurs whenever a user opts in for sharing basic website after previously opting out from it.

Important: This event will replace install.connected on Jan 1, 2023.

install.site.opt_out Occurs whenever a user opts out from sharing basic website after previously sharing it.

Important: This event will replace install.disconnected on Jan 1, 2023.

install.sdk.version.updated Occurs whenever an installation Freemius WordPress SDK version is updated.
install.title.updated Occurs whenever an installation’s site title is updated.
install.trial.cancelled Occurs when a trial is cancelled.
install.trial.expired Occurs when a trial is expired.
install.trial_expiring_notice.sent Occurs when an email has been sent to the user notifying them the trial period is about to end.
install.trial.extended Occurs whenever a trial is manually extended.
install.trial.plan.updated Occurs whenever a trial plan is updated.
install.trial.started Occurs when a free trial is started on an existing product install.
install.uninstalled Occurs whenever the plugin/theme is uninstalled.
install.updated Occurs whenever an installation data is updated (in addition to specific install update events).
install.url.updated Occurs whenever an installation’s home URL is updated.
install.user.opt_in Occurs whenever a user opts in for sharing their basic profile info after previously opting out from it.
install.user.opt_out Occurs whenever a user opts out from sharing their basic profile info after previously sharing it.
install.version.downgrade Occurs whenever the plugin/theme is downgraded to a lower version (not related to the plan).
install.version.upgraded Occurs whenever the plugin/theme is upgrade to a newer version (not related to the plan).
license.activated Occurs whenever a license is activated (also triggered automatically after a successful plan upgrade).
license.blacklisted_site.deleted Occurs when a blacklisted site has been removed in the User Dashboard.
license.cancelled Occurs when a license is cancelled.
license.created Occurs whenever a license is created.
license.deactivated Occurs whenever a license is deactivated.
license.deleted Occurs when a license has been deleted in the Developer Dashboard.
license.expired Occurs when a license expires.
license.expired_notice.sent Occurs when a license expired email notice has been sent to the user.
license.extended Occurs whenever a license is extended by the developer from the dashboard.
license.ownership.changed Occurs whenever a license ownership is changed by the developer from the dashboard.
license.quota.changed Occurs whenever a license quota is changed by the developer from the dashboard.
license.renewal_reminder.sent Occurs when a license renewal reminder email has been sent to the user.
license.shortened Occurs when a license has been shortened in the User/Developer Dashboard.
license.site.blacklisted Occurs when a site has been blacklisted in the User Dashboard.
license.site.whitelisted Occurs when a site has been whitelisted in the User Dashboard.
license.trial_expiring_notice.sent Occurs when a courtesy trial expiration reminder email has been sent to the user. For 7-day trials, the email is sent 2 days prior to the trial expiration. For longer trials, the email is sent 7 days prior to the trial expiration.
license.updated Occurs whenever a license is updated (in addition to specific license update events).
license.whitelisted_site.deleted Occurs when a whitelisted site has been removed in the User Dashboard.
member.created Occurs whenever a developer is added as a team member.
member.deleted Occurs whenever a member is removed from a team.
member.updated Occurs whenever a team member role is updated.
payment.created Occurs whenever a successful payment is created. There’s no dedicated event for subscription renewals. To trigger an action only for renewals, your webhook needs to check the is_renewal flag of the event’s payment object provided with the event’s metadata.
payment.refund Occurs whenever a payment refund is processed.
payment.dispute.created Occurs whenever we notified about a payment disputed by a customer.
payment.dispute.closed Occurs whenever a payment dispute is closed by refunding the disputed payment.
payment.dispute.lost Occurs whenever a payment dispute is closed in favor of the customer.
payment.dispute.won Occurs whenever a payment dispute is closed in your/seller’s favor.
plan.created Occurs whenever a plan is created.
plan.deleted Occurs whenever a plan is deleted.
plan.lifetime.purchase Occurs whenever a user purchases a lifetime package (doesn’t matter which plan).
plan.updated Occurs whenever a plan details are updated.
plugin.addresses.updated Occurs whenever email addresses are updated.
plugin.created Occurs whenever a plugin/theme is created.
plugin.deleted Occurs when a plugin has been deleted in the Developer Dashboard.
plugin.feature.created Occurs whenever a plan feature is created.
plugin.free.downloaded Occurs whenever a free plugin/theme code version is downloaded.
plugin.premium.downloaded Occurs whenever a premium plugin/theme code version is downloaded.
plugin.updated Occurs when a plugin has been updated in the Developer Dashboard.
plugin.version.deleted Occurs whenever a deployed version is deleted.
plugin.version.deployed Occurs whenever a new plugin/theme version is deployed to Freemius.
plugin.version.released Occurs whenever a version is set as released.
plugin.version.beta.released Occurs whenever a version is released as beta.
plugin.version.release.suspended Occurs whenever a deployment release is suspended.
plugin.version.updated Occurs whenever an existing version is re-deployed to Freemius.
pricing.created Occurs whenever a new pricing is added to a plan.
pricing.deleted Occurs whenever one of the plan pricing is deleted.
pricing.updated Occurs whenever a plan pricing is updated.
pricing.visit Occurs when a user has visited the pricing table via the WordPress admin or popup checkout modal.
review.created Occurs when a new plugin or theme review has been created.
review.deleted Occurs when a review has been deleted in the Developer Dashboard.
review.requested Occurs when a new review request email has been sent to the user. This is sent 7 days after purchase to users that haven’t canceled the license yet, were not refunded, and are using the product on at least one website.
review.updated Occurs when a new review has been updated in the Developer Dashboard.
store.created Occurs when a new store has been created (e.g. when a new Freemius account has been created).
store.dashboard_url.updated Occurs when the store’s dashboard URL is updated.
store.plugin.added Occurs when a product is added to a store.
store.plugin.removed Occurs when a product is removed from a store.
store.url.updated Occurs when a store’s URL is updated
subscription.cancelled Occurs whenever a subscription is cancelled.
subscription.created Occurs whenever a subscription is created.
subscription.renewal_reminder.sent Occurs whenever an annual renewal reminder email is sent (30 days before the automatic renewal).
subscription.renewal_reminder.opened Occurs whenever an annual renewal reminder email is opened.
subscription.renewal.failed Occurs whenever a renewal payment processing is failed .
subscription.renewal.failed.last Occurs when the latest subscription renewal attempt has failed.
subscription.renewal.failed_email.sent Occurs whenever a failure renewal processing email is sent to the buyer.
subscription.renewal.retry Occurs whenever a renewal payment retry is processed.
subscription.renewals.discounted Occurs whenever a special subscription cancellation promo is applied.
user.beta_program.opted_in Occurs when a user has opted into a plugin or theme beta program.
user.beta_program.opted_out Occurs when a user has opted out of a plugin or theme beta program.
user.billing.updated Occurs whenever a customer billing information is updated (e.g. address, VAT ID, company name).
user.billing.tax_id.updated Occurs whenever the tax ID associated with the user’s billing is changed.
user.card.created Occurs whenever a new card is added to a user’s dashboard account. This is similar to card.created but also logs the connection between a user and a credit card. Different users in the system can be associated with the same credit card (e.g. if a company with multiple people is using the same credit card for all their purchases).
user.created Occurs whenever a new user installs the plugin/theme and opts in.
user.email.changed Occurs whenever a user update their email address.
user.email.verified Occurs when a user email is verified (usually via email confirmation). If you need to use this event, please contac us first via [email protected].
user.email_status.bounced Occurs when a transactional email sent to a user bounces, which also changes the user’s email_status property to 'bounced'.
user.email_status.delivered Occurs when a transactional email sent to a user is successfully delivered and only if the user’s previous deliverability state (aka the email_status property) was not empty before. I.e., this event is only triggered after a previous email has bounced or dropped.
user.email_status.dropped Occurs when a transactional email sent to a user is dropped, which also changes the user’s email_status property to 'dropped'.
user.marketing.opted_in Occurs when a user has opted into a plugin or theme marketing material (emails). This event only occurs after a change in the marketing opt-in state and is not triggered when a user is created.
user.marketing.opted_out Occurs when a user has opted out of a plugin or theme marketing material (emails). This event only occurs after a change in the marketing opt-in state and is not triggered when a user is created.
user.marketing.reset Occurs when a user’s marketing status has been reset.
user.name.changed Occurs whenever a user update their name.
user.support.contacted Occurs when a user contacts support through the User Dashboard contact form.
user.trial.started Occurs when a user registers for a trial.
webhook.created Occurs whenever a webhook is created.
webhook.deleted Occurs whenever a webhook is deleted.
webhook.updated Occurs whenever a webhook is updated.