Integrating lead forms with Webhooks

You're ready to use the powerful lead forms within your Landing Stories. Now let's help you get the collected data with Webhooks.

In this article we're assuming you created a lead form in Tappable and you are building the endpoint where the data will be sent to.

If instead you simply want to test and see what data we send, head over to https://webhook.site/ to instantly create a test webhook where you will be able to inspect the data.

Data is sent to your webhook with a POST request, and a JSON encoded body. The structure of the body is as follows:

{
  "id": "Ne4f02Eb8gKw8NJtyzUhT",
  "form": {
    "text": "Single line of text",
    "textarea": "Multiple lines of text.\r\nCan include line breaks.",
    "number": "100",
    "checkbox": ["Option 1", "Option 3"],
    "radio": "Option 2",
    "consent": "true",
    "hidden": "value"
  },
  "meta": {
    "timestamp": 1644334678032,
    "form": "tzrnukN7",
    "story": "https://amphtml.tappable.link/form",
    "query": { "utm_source": "tappable", "utm_medium": "story" },
    "city": "Brussels",
    "country": "BE",
    "continent": "EU",
    "longitude": "4.34800",
    "latitude": "50.82740",
    "eu": true,
    "timezone": "Europe/Brussels",
    "browser": { "name": "Chrome", "version": "97.0.4692.99", "major": "97" },
    "device": {},
    "os": { "name": "Mac OS", "version": "10.15.7" }
  }
}

The JSON payload contains 3 keys.

id is a unique ID generated with each form submission.
form contains the data filled in the form. Each key corresponds to a field.
meta is all the additional information related to the form submission, such as the timestamp, the story, the form ID, an approximate location, the browser and the URL search parameters.

Your endpoint should parse the JSON data and store it in a database, or process the data in a way that is beneficial to your business. It's up to you to do whatever you want with the data.

Your endpoint only has to return a HTTP response with a status smaller than 400. This indicates to us the delivery was successful. If we receive a HTTP status of 400 or higher, we will assume the endpoint had an error.

In case of an endpoint error, the Webhook JSON data will be emailed to the email address linked to the form.

NOTE: for GDPR compliance, we do not store data anywhere. You are responsible for storing the lead data. We can NOT retrieve the data if you loose it, or if your endpoint fails silently (e.g. returning a HTTP 200 status code when the endpoint had an error).