Safe thank-you redirects

1. Add the external form stylesheet

Save the CSS below as a separate file in your website. HTML examples load it from /static/assets/css/form-helper.css; React and Vue import ./form-helper.css beside the component. Adjust the path to match your site and confirm the file loads before publishing. The generic .form-helper class moves the text input off-screen without the hidden attribute or display: none. Keep tabindex="-1", autocomplete="off", and aria-hidden="true". New forms use fax_number; existing forms keep their saved name. Match Settings → Delivery & spam → Honeypot field in HTML, JSON, and drafts. To rename an existing trap, update both the setting and the website together. Never use a name that also collects a real visitor answer.

.form-helper {
    position: absolute;
    left: -9999px;
    width: 1px;
    height: 1px;
    overflow: hidden;
    pointer-events: none;
}

• Download the stylesheet

2. Choose a thank-you page

A thank-you redirect takes visitors to a page you control after Qubeforms receives their submission. Create that page on your website first. Then, as the form owner, open Settings → Delivery & spam, find Safe redirect allowlist, enter one complete URL per line, and select Save delivery settings. Allowed origins and redirect destinations are separate settings: adding a website to one list does not add it to the other.

https://www.example.com/thank-you
https://www.example.com/contact/received

3. Keep the allowlist specific

Use full https:// URLs in production. HTTP is supported for local testing. Relative paths such as /thank-you, wildcard entries, non-HTTP schemes, and URLs containing a username or password are not valid allowlist entries. Keep to 50 entries or fewer, with each URL no longer than 2,048 characters. An empty redirect allowlist permits no requested redirect. It does not prevent submissions that omit a redirect destination.

4. Understand destination matching

An entry allows its matching URL and slash-separated descendant paths. For example, https://www.example.com/thank-you also allows https://www.example.com/thank-you/order, but not https://www.example.com/thank-you-other. Allowing only the site’s root permits paths across that site, so choose a narrower path when possible. Current matching ignores letter case and trailing slashes. Query strings and fragments are part of the compared value: use a fixed URL and add the exact variant you intend to request. Do not put private submission fields, read keys, or download links into a redirect URL.

5. Request the redirect from an HTML form

Saving an allowlist does not select a default destination. Include a hidden _cf_redirect input in each submission to request one of the approved URLs. Replace the public key and destination in this example, and use your configured honeypot and CAPTCHA fields when applicable. A successful native HTML submission receives HTTP 303 and the browser opens the destination with GET.

<link rel="stylesheet" href="/static/assets/css/form-helper.css">
<form id="redirect-form" action="https://api.qubeforms.io/v1/cf_pk_YOUR_KEY/submissions" method="post">
  <label for="contact-email">Email</label>
  <input id="contact-email" name="email" type="email" required>

  <label for="contact-message">Message</label>
  <textarea id="contact-message" name="message" required></textarea>

  <input type="hidden" name="_cf_redirect" value="https://www.example.com/thank-you">
  <input class="form-helper" name="fax_number" type="text" tabindex="-1" autocomplete="off" aria-hidden="true">
  <button type="submit">Send</button>
</form>

6. Use the endpoint query parameter if needed

If your form builder cannot add a hidden field, the submission endpoint also accepts a URL-encoded redirect query parameter. The destination still must match the form’s safe redirect allowlist. The submitted _cf_redirect field takes precedence when present, so remove a blank or outdated field if you want the query parameter to apply. Use one method consistently to make the integration easier to maintain.

https://api.qubeforms.io/v1/cf_pk_YOUR_KEY/submissions?redirect=https%3A%2F%2Fwww.example.com%2Fthank-you

7. Handle redirects in JavaScript

When you send Accept: application/json, Qubeforms returns HTTP 201 with a redirect_url value instead of navigating the browser. Your script decides whether to navigate or show an inline confirmation. Send _cf_redirect in the JSON or FormData body, check the HTTP result, and navigate only after success. Add this script after the HTML example above. It uses FormData, which also works if your paid-plan form has file inputs. Let the browser set the multipart content type.

<p id="redirect-status" role="status"></p>
<script>
const form = document.querySelector('#redirect-form');
const status = document.querySelector('#redirect-status');
const button = form.querySelector('button[type="submit"]');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  if (button.disabled) return;
  button.disabled = true;
  status.textContent = 'Sending…';
  try {
    const response = await fetch(form.action, {
      method: 'POST',
      headers: { Accept: 'application/json' },
      body: new FormData(form),
    });
    const result = await response.json().catch(() => null);
    if (!response.ok || !result?.ok) {
      status.textContent = result?.error?.message || 'Please check your submission before retrying.';
      return;
    }
    if (result.redirect_url) {
      window.location.assign(result.redirect_url);
    } else {
      status.textContent = 'Your submission was received.';
    }
  } catch {
    status.textContent = 'We could not confirm receipt. Check before submitting again.';
  } finally {
    button.disabled = false;
  }
});
</script>

8. Test and troubleshoot the result

Submit from an allowed website origin and confirm both that the record arrived and that the correct page opens. HTTP 422 with “Redirect URL is invalid” means the requested URL is malformed; “Redirect URL is not on this form’s allowlist” means it is not approved. Check spelling, scheme, host, path, and any query string. A redirect-validation error can occur after the submission has been stored, so check the inbox before resubmitting. Seeing JSON with redirect_url is expected when the request asks for JSON; your script must perform the navigation. A missing destination produces no automatic redirect.

9. Keep the confirmation accurate

A redirect confirms that the submission request was accepted, not that notification emails have been delivered or that spam screening placed it in the Inbox. Use a neutral message such as “Thank you. We received your submission.” Keep private field values off the page unless your own application authenticates access to them. When changing your thank-you URL, update both the allowlist and the form’s requested destination, then test again before removing the old page.

• Your first HTML form
• AJAX and JSON submissions
• Test your form before publishing