How to use the reCAPTCHA widget


Google reCAPTCHA is a free service that protects your website from spam and abuse. reCAPTCHA uses an advanced risk analysis engine and adaptive CAPTCHAs to keep automated software from engaging in abusive activities on your site. It does this while letting your valid users pass through with ease.

reCAPTCHA offers more than just spam protection. Every time our CAPTCHAs are solved, that human effort helps digitize text, annotate images, and build machine learning datasets. This in turn helps preserve books, improve maps, and solve hard AI problems.

How the reCAPTCHA widget works

reCaptcha works in three steps:

  1. The widget is rendered. The widget contains a public “site key” that can be generated for a specific url. This site key can be generated on the Google reCAPTCHA site.

  2. The user clicks on the checkbox to confirm that he/she is not a robot. The browser will communicate with google and a response code is generated and stored in a data field. This response code confirms that the user is indeed not a robot. The user can proceed with whatever he/she was doing, now that it is verified he/she is not a robot.

  3. The wem runtime server can verify with google that the response code is valid. This step is strictly not necessary, but it is strongly advised to do this. The validation is done by using a HTTP request node. The request contains the response code, the “secret key” and the client IP address. The response is a JSON message.

You can find more information about Google reCAPTCHA on their introduction page.

How to use the widget

Before you start, get your site key and secret key from the Google reCAPTCHA site. You need these keys. The site key is needed in the widget itself, while the secret key is needed for communication between your site and Google (usually used to verify the Google response). When you want to use the reCAPTCHA widget, make sure you have created a number of database fields that you need to store request and response information:

  • a textfield for the request body;

  • a textfield for the response body;

  • a textfield for the response.

In the flowchart that contains the form where you use the widget, clear the response field to make sure that every time you use the widget, you start with a clean situation.

Next, add the widget to your form. The widget has two properties that need your attention:

  • Site Key: enter the key you generated on the Google reCAPTCHA site;

  • Response: this should point to reCAPTCHA response data field.

The next action on the form should depend on the response from reCAPTCHA: usually the user can only continue when it has been established that he/she is not a robot. Mostly the next action is to click a button (“Next”, “Submit”, etc.). Which means that a check is needed for the next action to be possible. There are two possibilities:

  • Simply check if the reCAPTACHA response field has a value.

  • Double check if the response value is correct by asking Google to check the response value. It is advised to do this.

To check the response value, do the following:

  1. Set the reCAPTACHA request body data field (using an assignment node) to the following: "secret=" + UrlEncode("<secret key>") + "&response=" + UrlEncode([Widgets.ReCaptchaResponse]) + "&remoteip=" + UrlEncode(IpAddress()) The secret key is the key you got from Google. response field should point to the reCAPTCHA response data field. remoteip field is the IP address of the client that accesses this form.

  2. Use an HTTP POST request (using an HTTP request node) to validate the response value. The request body is the reCAPTCHA request body data field. The response body is the reCAPTCHA response body data field.

  3. Press the Edit Request Headers of the HTTP request node, and make sure that “Content-Type” field is set to “application/x-www-form-urlencoded”.

  4. Finally check the response body, to find out whether the validation was successful or not. More details can be found here:

When the validation was successful, the next user action can be executed.


  • one way to accomplish the validation above, is to create a button, which starts a flowchart. This flowchart contains the actual check and can define the action to be taken when the validation is either successful or not.

  • If you use the site key and secret key multiple times, it may be useful to store these keys in a calculated fields. One field contains the site kay, another field the secret key. This way you can easily refer to these fields, insteds of entering the keys very time you need it.

Last updated