Skip to main content

Integrating Trial Hook with your forms

How to integrate Trial Hook with your landing pages and forms

Updated this week

There are 3 ways to integrate your website pages and forms with Trial Hook.

When you just start with Trial Hook, we will ask you to test your integration with one of the methods below.
​
Once we've confirmed we are receiving the data, you are all set to start using Trial Hook!

We have prepared detailed integration guides for a selection of the most popular tools. Check it out here.

JS Snippet

What is it

A small block of JavaScript that you can place into the <head> section of your website/landing page. Something like the below:
​

<script src="https://cdn.trialhook.com/trialhook.js" 
  defer crossorigin="anonymous" 
  data-apikey="{{your api key}}">
</script>

Where to use it

You can use the JS snippet on any website or landing page that includes a form where your visitors can enter their email address. The form can include any other fields in addition to the email field.

You need to have appropriate access in your website/landing page creation tool to edit custom scripts to be inserted in the <head> section.

The JS snippet works with any form (static or dynamic), except for embedded forms that are loaded as an iframe (e.g., Tally, Typeform, etc.).
​

Dynamically embedded forms that append elements to the DOM of the page work just fine (e.g WisePops).

For Tally, Typeform, and others, integrate your form with Trial Hook via Webhook. We've also prepared separate integration guides for various form tools and webpage builders.

How does it work

  1. Trial Hook JS snippet looks for forms on the page on load and those that are dynamically loaded after the page load:
    ​

    1. If a form is found, the snippet takes the values of the inputs of the first form on form submission.

      1. if multiple forms are found on the page, the first form with a field containing an email takes precedence

    2. If the snippet finds a form with a custom class trialhook-form - that takes precedence over other forms on the page

      1. if multiple instances of trialhook-form are found on the page, the first one takes precedence.
        ​

  2. Within the form the snippet finds, it selects the inputs:
    ​

    1. that are visible and not hidden

    2. with type email or name containing "email" or id containing "email"

    3. that have a valid email address on submission
      ​

  3. Once the form is submitted, the snippet intercepts the submission and sends an XHR request to our endpoint, passing the email address from the form.
    ​

  4. The snippet has progressive retry logic, trying to submit the data 4 times with short intervals.
    ​

  5. Once the request to our endpoint is successful (or fails after 4 attempts), the snippet proceeds with the original form submission action.

Webhook

What is it

A webhook URL that accepts various types of payload from 3rd-party tools.


Where to use it

You can use the webhook with your form tool or other systems that collect the user's email address and can pass it over as part of the payload.


How does it work

Trial Hook uses asynchronous processing of requests. The requests are placed into the processing queue. When you trigger the webhook, the request is placed into the queue. Processing of the request may happen with some delay.

Webhook POST URL:

https://api.trialhook.com/v1/webhook/{{your api key}}

Webhook URLs are unique for every user. You can find your URL in the Settings section of Trial Hook.
​
​Headers:

We do not require any specific headers to be set when triggering the webhook.
​

Body:
We don't have any specific requirements for the payload that a 3rd party tool might send when triggering the webhook. As every tool has its own payload format, we extract the first value that matches the format of an email address.

API request

What is it

A POST endpoint that accepts email as a body parameter.


Where to use it

You can use the endpoint in your app/website where you collect the user's email address and want to enrich their profile.


How does it work

Trial Hook uses asynchronous processing of requests. The requests are placed into the processing queue. When you receive a success response from the API endpoint, this indicates that the request has been successfully placed into the queue. Processing of the request may happen with some delay.

POST URL:

https://api.trialhook.com/v1/event/signup


​Headers:

Name

Value

Content-Type

application/json

X-ApiKey

Your API key

Body:

{
  "Email": "[email protected]"
}


Here's the full cURL example:

curl -X "POST" https://api.trialhook.com/v1/event/signup \
-H "X-ApiKey: {{your api key}}" \
-H "Content-Type: application/json" \
-d '{ "Email": "[email protected]" }'

Responses:

Code

Value

200

{
  "Success": true
}

401

{
  "Success": false,
  "Error": "Unauthorized"
}

404

{
  "Success": false,
  "Error": "Not Found"
}
Did this answer your question?