How it works
When someone submits a form on your website, you can pass it to The Layer in one step. The Layer finds the right Lead or Customer, updates or creates the record, and raises an opportunity for enquiry forms. Your website does not need any customer data to do this.
A visitor submits a form on your site.
The form posts to your own back end, not straight to The Layer.
Your back end runs its spam checks, then makes one signed call to The Layer.
The Layer matches and routes the submission, and replies that it has been received.
This article is about a form on your own website. A "Layer form", built inside The Layer, is different: you do not post anything, because The Layer already has the submission, and the same matching and routing can run on it.
Before you start
The receiving end is a webhook automation in The Layer's Automation Builder. Your Layer contact can set it up and send you its details, or you can set it up yourself (see "Set it up in The Layer" below). Either way, you need two things from it:
an inbound webhook URL that ends with a token, and
a signing secret (it starts with whsec_).
Keep the signing secret on your server, like a password. It must never appear in your web pages, and the call to The Layer must be made from your server, not from the browser.
Set it up in The Layer
If your Layer contact is setting this up for you, you can skip this. To do it yourself:
In The Layer, open Settings, then Automation Builder.
Install the ready-made recipe Website form to Lead or Opportunity from the recipe gallery, or build the Webhook automation yourself. It receives the submission your website posts and routes it: matching a Lead or Customer, creating or updating the record, and raising an opportunity for your enquiry forms. (The recipe needs no connector and requires signing.)
List which form ids count as enquiry forms, so those submissions raise an opportunity (see "Which fields to send" for what a form id is).
Deploy the automation. Its webhook URL then appears in the automation's webhook panel, carrying a unique token.
In that panel, choose Reveal to show the signing secret and copy it. You can Rotate it later if it ever needs to change.
Give the webhook URL and the signing secret to whoever builds the website call, separately and securely.
Send the form
Make an HTTP POST with a JSON body. The token at the end of the URL identifies your automation.
POST https://webapi.thelayer.com/api/AutomationInbound/Receive/{token}
Content-Type: application/json
X-Layer-Timestamp: 1700000000
X-Layer-Signature: sha256=3f9a...
{"formId":"quote","email":"[email protected]","firstName":"Sam","company":"Acme Ltd"}Sign each request
Every request is signed, so a leaked URL on its own cannot be used. Work out the signature like this:
signedPayload = "{X-Layer-Timestamp}.{the raw request body}"
signature = lowercase hex of HMAC-SHA256(your signing secret, signedPayload)Then send two headers with the request:
X-Layer-Timestamp: the current time in Unix seconds.
X-Layer-Signature: sha256= followed by the signature. The sha256= prefix is optional.
Sign the exact bytes you send as the body, and sign at the moment you send. A timestamp more than five minutes from our clock is rejected, which stops anyone replaying a captured request, so keep your server clock in sync.
The call to The Layer must be made from your server. The signing secret stays on your server and never reaches the browser, and the endpoint does not accept cross-origin calls from a web page.
Which fields to send
email is how The Layer matches the submission to a Lead or Customer.
formId is your own short name for the form that was submitted, and you choose it (for example "quote" or "newsletter"). It does two jobs: if it is on the automation's list of enquiry forms, the submission also raises an opportunity for someone to follow up; and it is written on the note, so you can see which form each record came from. A form id that is not on the enquiry list, or no form id at all, simply creates or updates the Lead or Customer with no opportunity.
Other field names are matched loosely, so first_name, First Name and firstName all work. Send first name, last name, company, phone, and any campaign fields you have.
What you get back
202: received. Processing happens in the background, so show your visitor a thank-you page straight away.
413: the body is too large (over 256 KB). Send less.
404: the token is wrong or inactive, or the signature did not check out. The Layer returns the same 404 for all of these on purpose, so check your token and signing secret.
Sending the same submission twice is safe: identical requests are de-duplicated, so a retry will not create a duplicate.
Stop spam
Spam filtering is done on your back end, before you forward anything:
a honeypot field that real people never fill, and
a CAPTCHA that you verify on your server.
Example and testing
Ask your Layer contact for the sample pack. It has a small running example (an HTML form and a back end that signs the request and posts it) and the signing code in C#, PHP and Python, so you can lift the few lines that fit your platform.
Need a hand? Contact your Layer team and we will help your developers get set up.