Webhook

Overview

Use webhooks to get notifications about events in your app, other apps, or the Wix site:

  • Provisioning events – when a user adds or removes your app.
  • Billing events – when a user upgrades your app, makes an in-app purchase, requests to cancel your app’s premium plan, or when the premium plan ends.
  • Events related to the user’s contacts and site visitors – when a contact is created/updated in the user’s site, and when a site visitor performs an action in the site, like a purchase.
How Does It Work?

Here’s how to use webhooks in your app:

  1. Register for webhooks in the Dev Center.
  2. Receive webhooks when an event occurs. We send an HTTPS POST request to your server URL with the event’s data. Find out more about the request parameters.
  3. Verify the webhook’s signature, to make sure that the webhook was sent by Wix and not a third party.

We do our best to preserve timeliness and order in events. However, keep the following in mind when using webhooks:

  • We can’t guarantee that you’ll receive messages immediately and in the right order. When we detect an event delivery failure, we’ll try to deliver the event to your app three times during the first 24 hours from the time the event occurred. However, you might not receive messages in the order in which they occurred.
  • Make sure your app can handle receiving the same event more than once. We store copies of your app events on multiple servers for redundancy and high availability. On rare occasions, one of the servers storing a copy might be unavailable when you receive the event. The copy won’t be deleted from the unavailable server, so you might receive the same event more than once.
Register for Webhooks

Register in the Dev Center to receive events relevant to your app. When an event occurs, we send an HTTPS POST request to your server URL with the event’s data.

Important:
Use a server that supports HTTPS.

How to register for billing and provisioning events:

  1. Go to the Register Your App tab in your app’s page.
  2. In the App Components area, select Add new Component > Server.
  3. Enter the HTTPS URL for the server you want to get the webhook.
  4. Choose the events you want to receive in your app and click Add.

How to register for contact/activity events:

  1. Go to the WixHive API tab in your app’s page.
    Note: You’ll only see this tab once your mockups were approved. You won’t see this tab in test apps or if you’re in the proposal/mockup review stages.
  2. In the Register to get the WixHive events area, enter the HTTPS URL for the server you want to get the webhook.
  3. Choose the events you want to receive in your app and click Save.
Request Parameters

Each webhook is sent to your server endpoint with the following request parameters.

Parameter Type
NameValue
Verify the Signature

We send every POST request with a digital signature in the x-wix-signature header to signify that the calling party is indeed Wix.

Check the signature you received is from Wix:

  1. Sort all request parameters by parameter name (in ascending alphanumeric order) and concatenate their values with only a line break (n) as a separator. The request parameters include the following:

    a. Query parameters, all except for the signature parameter

    b. These headers with the x-wix- prefix: application-id, instance-id, event-type, timestamp, and event-id. For parameters with multiple values, trim and concatenate values with a comma (,).

  2. Concatenate, in the following order, and separate by a line break (n)

    a. HTTP method, converted to uppercase

    b. All values from the sorted request parameters (the output of #1)

    c. The request body

  3. Compute the HMACSHA-256 of the combined information using your app secret key.
  4. Encode the hash to a Base64 string.
  5. Compare the encoded string to the x-wix-signature header.

Code samples:

Provisioning Events

You can receive these provisioning events:

  • /provision/provision – a user added your app
  • /provision/disabled – a user removed your app

Webhook/provision/provision

This event is posted when the app is added to a website. If the website was never saved, the event will be sent only after the user saves the website.

Webhook Data:

Webhook/provision/disabled

This event is posted when all components of the app are removed from a website. If the website has never been saved, the event will be sent only after the user saves the website.

Webhook Data:

Billing Events

You can receive these billing events:

  • /billing/upgrade – a user upgraded your app or made an in-app purchase
  • /billing/statuschanged – a change in the user’s status relating to premium and in-app purchases
  • /billing/cancel – a user cancelled your app’s premium plan
Note:
If you register for /billing/statuschanged, you’ll receive cancel and upgrade events – so there’s no need to also register for /billing/upgrade and /billing/cancel. Check the event-type field to know which event occurred.

Webhook/billing/upgrade

This event is posted when a site owner purchases a premium package of the app, or makes an in-app purchase.

To check if a user upgraded your app, use the app instance parameter – here’s how. (Don’t rely only on the webhook!)

Note:
If you registered for the /billing/statuschanged event, you’re already set up to receive the upgrade event – so there’s no need to also register for /billing/upgrade.

Webhook Data:

Webhook/billing/statuschanged

The statuschanged event is posted when there’s a change in a user’s subscription, like an upgrade or cancellation request.

We report the following subscription changes:

  • PURCHASE_IMMEDIATE: A site owner upgraded your app or made an in-app purchaseThis event is the same as /billing/upgrade – so if you register for /billing/statuschanged, there’s no need to also register for /billing/upgrade.
  • CANCEL_REQUESTED: A site owner requested to cancel the app’s premium plan. The site is entitled to premium services/features until the end of the current billing cycle.
  • CANCEL_RESCINDED: After requesting to cancel the app’s premium plan, the site owner now cancelled the request – and will keep the premium plan.
  • CANCEL_IMMEDIATE: The site is no longer using this premium plan. This event is the same as /billing/cancel – so if you register for /billing/statuschanged, there’s no need to also register for /billing/cancel.
    Important: This event is not sent when a user’s in-app purchase credit ends – you’ll need to keep track of the user’s balance.
Important:
Make sure to only change a user’s subscription when your app receives PURCHASE_IMMEDIATE and CANCEL_IMMEDIATE. Users who cancel an app’s premium plan are still entitled to premium services, so don’t change their premium status when your app receives CANCEL_REQUESTED and CANCEL_RESCINDED.

Webhook Data:


 

Webhook/billing/cancel

This event is posted when the app’s premium plan ends due to user cancellation or billing system cancellation.

Note:
If you registered for the /billing/statuschanged event, you’re already set up to receive the cancel event – so there’s no need to also register for /billing/cancel.

Webhook Data:

Contact/Activity Events

You can receive these events:

  • /contacts/created – a contact was created in the user’s site
  • /contacts/updated – a contact was updated in the user’s site
  • /activities/posted – a site visitor performed an activity in the user’s site
Note:
Need more details about these events? You can use the WixHive platform to get more information.

Webhook/contacts/created

This event is posted when a new Contact is created by any app installed in the website.

Webhook Data:


 

Webhook/contacts/updated

This event is posted when a Contact is updated by any app installed in the website.

Webhook Data:

Webhook/activities/posted

This event is fired when a new activity is posted by any app installed in the website.

Webhook Data:

Was this page helpful?

What can we do to improve it?

What did you like about it?