Introduction

Wix Forms events are fired in your site's backend when certain events related to forms occur in your site's backend. You can write event handlers that react to these events. Event handler functions receive data that corresponds to the event that has occurred. Use event handlers to create custom responses to forms events.

Note: Backend events don't work when previewing your site.

To add a forms event handler, add an events.js file to the Backend section of your site if one does not already exist. All event handler functions for your site are defined in this file.

Event handler functions are defined using the following pattern:

Copy

For example, an event handler that handles form submission updates looks like this:

Copy

Did this help?

onSubmissionCreated( )

Triggered when a submission is created.

Method Declaration

Copy

function wixForms_onSubmissionCreated(event: SubmissionCreated): void;

Method Parameters

eventSubmissionCreated

Information about the created submission and metadata for the event.

Example shown:An event that triggers when submission is created

JavaScript


// Place this code in the events.js file
// of your site's Backend section.
// Add the file if it doesn't exist.

export function wixForms_onSubmissionCreated(event) {
  const entityId = event.entity._id;
  console.log(`Created submission with the id: ${entityId}. Event details: `, event)
}

/* Full event object:
{
    "entity": {
        "formId": "21bcb6c7-02b3-4ed1-b6db-7856094fac03",
        "namespace": "wix.form_app.form",
        "status": "PENDING",
        "submissions": {
            "first_name": "Patsy",
            "last_name": "McBride"
        },
        "revision": "1",
        "owner": {
            "applicationId": "151e476a-715e-ec33-db9a-a7ff4d51f70a"
        },
        "submitter": {
            "applicationId": "151e476a-715e-ec33-db9a-a7ff4d51f70a"
        },
        "seen": false,
        "_id": "f8281b62-1b2f-45bf-ba7d-f041d7653d2d",
        "_createdDate": "2023-12-28T12:55:55.630Z",
        "_updatedDate": "2023-12-28T12:55:55.746Z"
    },
    "metadata": {
       "entityId": "f8281b62-1b2f-45bf-ba7d-f041d7653d2d",
       "eventTime": "2023-12-28T12:55:55.630Z",
       "id": "a92d9e8b-abd7-4903-a954-5a6848f6f4eb",
        "triggeredByAnonymizeRequest": false
    }
}

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

onSubmissionDeleted( )

Notes:

The Form Submission API is only available in Wix Studio and Editor X.
The Form Submission API only works with the Wix Forms app. Call GetAppInstance to confirm that the app named wix_forms is installed on the site.

Triggered when a submission is deleted.

Method Declaration

Copy

function wixForms_onSubmissionDeleted(event: SubmissionDeleted): void;

Method Parameters

eventSubmissionDeleted

Information about the submission that was deleted.

Example shown:An event that triggers when a submission is deleted

JavaScript


// Place this code in the events.js file
// of your site's Backend section.
// Add the file if it doesn't exist.

export function wixForms_onSubmissionDeleted(event) {
  console.log(`Deleted submission. Event details: `, event)
}

/* Full event object:
{
    "metadata": {
       "entityId": "f8281b62-1b2f-45bf-ba7d-f041d7653d2d",
       "eventTime": "2023-12-28T12:55:55.630Z",
       "id": "a92d9e8b-abd7-4903-a954-5a6848f6f4eb",
        "triggeredByAnonymizeRequest": false
    }
}

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

onSubmissionUpdated( )

Triggered when:

Submission is updated.
Submission order status is updated.
Submission is confirmed.

Method Declaration

Copy

function wixForms_onSubmissionUpdated(event: SubmissionUpdated): void;

Method Parameters

eventSubmissionUpdated

Information about the updated submission and metadata for the event.

Example shown:An event that triggers when submission is updated

JavaScript


// Place this code in the events.js file
// of your site's Backend section.
// Add the file if it doesn't exist.

export function wixForms_onSubmissionUpdated(event) {
  const entityId = event.entity._id;
  console.log(`Updated submission with the id: ${entityId}. Event details: `, event)
}

/* Full event object:
{
    "entity": {
        "formId": "21bcb6c7-02b3-4ed1-b6db-7856094fac03",
        "namespace": "wix.form_app.form",
        "status": "PENDING",
        "submissions": {
            "first_name": "Patsy",
            "last_name": "McBride"
        },
        "revision": "1",
        "owner": {
            "applicationId": "151e476a-715e-ec33-db9a-a7ff4d51f70a"
        },
        "submitter": {
            "applicationId": "151e476a-715e-ec33-db9a-a7ff4d51f70a"
        },
        "seen": false,
        "_id": "f8281b62-1b2f-45bf-ba7d-f041d7653d2d",
        "_createdDate": "2023-12-28T12:55:55.630Z",
        "_updatedDate": "2023-12-29T11:53:55.746Z"
    },
    "metadata": {
       "entityId": "f8281b62-1b2f-45bf-ba7d-f041d7653d2d",
       "eventTime": "2023-12-29T11:53:55.746Z",
       "id": "a92d9e8b-abd7-4903-a954-5a6848f6f4eb",
        "triggeredByAnonymizeRequest": false
    }
}

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?