Integrating External Webhooks with Formulayt

Formulayt supports sending form submission data to external services via webhooks. Our webhook system is open-ended and can integrate with any endpoint that can receive and process JSON over HTTPS. This guide walks you through activating webhook integration, creating and managing webhook subscriptions, and handling form submission data in your own code or third-party service.

You can register your webhooks directly in our administration portal or via our API. Both approaches are detailed below.

For integrating specifically with Zapier, please refer to our dedicated Zapier article.

1. Activate the webhook integration and retrieve your credentials

Before your Formulayt forms can send data to your custom endpoint, you must:

Activate the Webhook integration in your Formulayt account
- This is done in the Apps section of your Formulayt dashboard
- As soon as the integration is active and set up for your account or individual form types, Formulayt will attempt to send form submission data through any valid webhooks you have registered
Obtain your Formulayt account ID and secret API key (if registering webhooks via our API)
- Your account ID uniquely identifies your Formulayt account
- The secret API key authenticates requests to Formulayt's subscription management endpoints (keep it private)
- If you suspect your API key has been exposed, revoke it in Formulayt and generate a new one

Important: Once the webhook integration is active and being used by one or more form types, if you do not register any valid subscriptions, form submissions will result in an error (NO_VALID_WEBHOOKS), and your users will be unable to submit forms.

2. Build your endpoint to accept incoming form submissions

Next, implement a listener (endpoint) on your server or application to handle the HTTP POST requests that Formulayt will send. This endpoint can be written in any language or framework as long as it can:

Accept HTTP POST requests
Parse incoming JSON data
Respond with an appropriate HTTP status code (usually 2xx on success or 4xx/5xx on errors)

2.1 Understanding the payload

When a user submits a form, Formulayt will POST a JSON payload to your configured target_url. The exact structure is account-specific (since every Formulayt account may have different default fields), but it is generally a flat JSON object containing:

One or more form fields from the submitted form (keys match your configured field names in Formulayt)
A serverTimestamp field indicating the time at which the submission was processed

Below is a generic example of what a form submission payload might look like. Actual field names will depend on the form fields you configure in Formulayt:

{
 "firstName": "John",
 "lastName": "Smith",
 "email": "john.smith@test.com",
 "company": "Test Company",
 "country": "GB",
 "phone": "+441234567890",
 "jobTitle": "Manager",
 "serverTimestamp": "2024-02-01T12:34:56.789Z" 
}

2.2 Basic endpoint example

Below is a simple, language-agnostic pseudocode for an endpoint that might receive and log the incoming submission:

POST /my-webhook-endpoint 

function handleFormulaytWebhook(request):
 // Parse the JSON body
 data = parseJSON(request.body)

 // Log or handle the data
 log("Received form submission from Formulayt:", data)

 // Return a success response
 return HTTP 200 OK

You can adapt this to your preferred language or web framework.

3. Register your endpoint with Formulayt

Once your endpoint is ready to accept data, you must inform Formulayt where to send form submissions. You can either do this directly within our administration portal in the webhook App settings, or follow the instructions below to register your webhook via our API.

Registering via the API

You do this by creating a subscription to a particular event (in this case, "form.submission").

3.1 Create a subscription

Send a POST request, formatted in JSON, to Formulayt's subscription creation endpoint:

POST https://app.gatedcontent.com/api/v1/subscriptions

Body JSON Field	Type	Required	Description
account_id	String	Yes	Your Formulayt account ID.
api_key	String	Yes	Your secret Formulayt API key.
event	String	Yes	form.submission
target_url	String	Yes	The full URL of the endpoint that will receive the submission payload.

Example request (cURL):

curl -X POST "https://app.gatedcontent.com/api/v1/subscriptions" \
-H "Content-Type: application/json" \
-d '{
"account_id": "YOUR_ACCOUNT_ID",
"api_key": "YOUR_API_KEY",
"event": "form.submission",
"target_url": "https://myapi.example.com/formulayt-webhook"
}'

Sample Response: A successful response (HTTP 200/201) returns a JSON object with the subscription ID as the body property, which you should store if you need to manage or remove the subscription later. In the example below, the subscription is 1.

{
"Error": false,
"Message": "SUCCESS",
"Body": 1
}

Important: Formulayt will also attempt to send a sample payload to your endpoint soon after this call, so ensure your endpoint is live and ready.

4. Testing and obtaining a sample payload

If you want to preview what data your endpoint will receive, you can retrieve a sample payload. This payload is generated based on some of your Formulayt account's key configured fields:

GET https://app.gatedcontent.com/api/v1/subscriptions/sample

Query Parameter	Type	Required	Description
account_id	String	Yes	Your Formulayt account ID.
api_key	String	Yes	Your secret Formulayt API key.
event	String	Yes	form.submission

Sample Response: The sample payload is contained in the Body property of the response (the exact fields will differ based on your account's form configuration). Note that for an actual form submission, you will only receive the contents of Body, not the wrapping object (see section 2.1 above).

{
   "Error": false,
   "Message": "SUCCESS",
   "Body": {
   "firstName": "John",
   "lastName": "Smith",
   "email": "john.smith@test.com",
   "company": "Test Company",
   "country": "GB",
   "phone": "+441234567890",
   "jobTitle": "Manager",
   "serverTimestamp": "2025-02-06T13:45:12.345Z"
   }
}

5. Deleting a subscription

If you need to stop receiving form submissions at a particular endpoint, you can delete the subscription by its ID:

DELETE https://app.gatedcontent.com/api/v1/subscriptions/:id

Parameter	Type	Required	Description
:id (URL)	String	Yes	The unique identifier of the subscription.
account_id	String	Yes	Your Formulayt account ID (in JSON body/query).
api_key	String	Yes	Your Formulayt API key (in JSON body/query).

5.1 Example request (cURL)

curl -X DELETE "https://app.gatedcontent.com/api/v1/subscriptions/SUBSCRIPTION_ID" \
-H "Content-Type: application/json" \
-d '{
"account_id": "YOUR_ACCOUNT_ID",
"api_key": "YOUR_API_KEY"
}'

Sample Response: A successful response should indicate "Subscription deleted".

{
"Error": false,
"Message": "SUCCESS",
"Body": "Subscription deleted"
}

Additional notes

Custom headers

You can add custom HTTP headers to all outgoing webhooks in the "HTTP Headers" area within the Webhook App settings in Formulayt
These can be used for adding secrets, CSRF tokens, or other information to verify the authenticity of the webhook origin

Data handling

Formulayt only relays your submission data and does not store it
If your endpoint is misconfigured or if you delete your subscription prematurely, submissions will be lost and cannot be retrieved later

Error handling

If your endpoint is down or returns a non-2xx status code, Formulayt will consider the submission delivery as failed
Formulayt does not implement an automatic retry mechanism, so ensure your endpoint is stable or implement your own failure handling

Security

Treat your Formulayt api_key like a password
You can use Google reCAPTCHA alongside your webhook to reduce spam submissions. Formulayt will handle the reCAPTCHA check once you activate this App. Refer to this article for further information

Integration priority

Once the webhook integration is active and you have at least one valid subscription, your forms will attempt to submit data to that subscription's target_url
Formulayt will attempt to deliver submissions to all registered webhook subscriptions

Testing

When you first create a subscription, Formulayt sends a sample payload to your target_url
You can also manually retrieve samples at any time using the GET /subscriptions/sample endpoint, as shown above