Send ClarNow responses to a webhook
A webhook sends every new response to a URL of yours as a JSON POST, the moment it is submitted. Use it to put leads into your own database, start a job on your server, or feed a tool ClarNow has no integration for.
What a webhook does
Section titled “What a webhook does”- One request per response, sent to every active webhook of the form as soon as the respondent submits.
- Answers ready to use. Every answer comes as a value for machines (numbers, ISO dates, phone numbers in E.164, yes/no as
true/false) and as one readable line of text. - Signed, if you want. With a signing secret, every request carries an HMAC-SHA256 signature so you can check it came from ClarNow.
- On the record. Every attempt is logged with its status code, for 30 days.
Requirements
Section titled “Requirements”- A ClarNow account on any plan, including Free.
- Edit access to the form.
- An endpoint that accepts
POSTrequests with a JSON body and answers within 10 seconds.
Add a webhook
Section titled “Add a webhook”-
Open the form in the ClarNow builder and go to Connect → Webhooks.
-
Click “Add Webhook” and enter your Endpoint URL.
-
Add a signing secret (optional, recommended). Click Regenerate to create a random one, or type your own. Copy it — your endpoint needs it to check signatures.
-
Keep “Active” on and click Add Webhook.
-
Send a test. Open the webhook in the list and click Send test. ClarNow posts a sample response built from the form’s questions, and the result appears under Recent deliveries.
The webhook fires for the next response. You don’t need to republish the form.
The payload
Section titled “The payload”An abridged real delivery:
{ "event_id": "evt_3kR9mQx7", "event_type": "response.completed", "created_at": "2026-07-31T15:01:36.093Z", "data": { "response_id": "rsp_8x2vLp", "response_url": "https://app.clarnow.com/form/frm_9qEDQG/results/answers?response=rsp_8x2vLp", "form": { "id": "frm_9qEDQG", "name": "Customer onboarding", "version": 12 }, "started_at": "2026-07-31T14:58:02.000Z", "submitted_at": "2026-07-31T15:01:36.093Z", "source": { "type": "embed", "embed_type": "popup", "referrer_url": "https://acme.com/pricing" }, "url_params": { "utm_source": "twitter" }, "variables": { "qualification": 20 }, "ending": { "id": "end_1", "type": "screen", "title": "Thanks!" }, "scoring": { "type": "lead", "score": 20 }, "fields": [ { "id": "f_plan", "ref": "plan", "type": "multiple_choice", "title": "Which plan fits you best?", "answered": true, "value": { "ids": ["c_pro"], "labels": ["Pro"], "other": null }, "text": "Pro" } ], "answers": { "full_name": "Ada Lovelace", "plan": { "ids": ["c_pro"], "labels": ["Pro"], "other": null } }, "answers_text": { "full_name": "Ada Lovelace", "plan": "Pro" } }}| Key | What it holds |
|---|---|
event_type |
response.completed, or webhook.test for a test (which also has "test": true and response_id: null). |
form.version |
The published version the response was submitted to. |
source, url_params |
Where the response came from — direct link or embed, referring page, and the query parameters the form was opened with, UTM tags included. |
ending |
The ending screen the respondent saw. |
scoring |
Quiz or scorecard result. Absent on forms without scoring. |
fields |
Every question of that version, in form order, answered or not. |
answers, answers_text |
The same answers keyed by each question’s reference — as values and as text. |
All times are ISO 8601 in UTC.
Read answers by reference, not position
Section titled “Read answers by reference, not position”Every question has a reference — the key it appears under in answers and answers_text. Name them in Form settings → References (for example email, budget, plan) and map answers.budget instead of fields[4]: a position changes whenever you add or move a question, a reference doesn’t. A renamed reference applies from the next publish, and anything mapped to the old name stops receiving it.
Values by question type
Section titled “Values by question type”| Question | value |
|---|---|
| Text, long text, email, website | string |
| Number, currency | number (currency also has the ISO code on the field) |
| Phone | E.164 string, "+12025550143" |
| Date / time | "2026-07-29" / "19:33" |
| Yes/No | true or false |
| Rating, scale | number, with max on the field |
| Choice, picture choice, dropdown, checkboxes, ranking | { ids, labels, other } |
| Matrix | [{ row: { id, label }, columns: [{ id, label }] }] |
| Contact | { first_name, last_name, email, phone } |
| Address | { address, address2, city, state, zip, country } |
| File upload | [{ id, name, size, mime_type, url }] — url works for 7 days |
| Payment | { amount, currency, status, payment_intent } |
| Calendly, Cal.com | { status, event_id, starts_at } |
An unanswered question has answered: false, value: null and text: "". A payment or booking that Stripe or the scheduling service did not confirm counts as unanswered.
Headers
Section titled “Headers”Content-Type: application/jsonUser-Agent: Clarnow-Webhooks/1X-Clarnow-Event-Id: evt_3kR9mQx7X-Clarnow-Event-Type: response.completedX-Clarnow-Delivery-Id: whd_7Pq2mX-Clarnow-Signature: t=1785510096,v1=5257a869e7…X-Clarnow-Event-Id is the same for every endpoint of the form — use it to skip duplicates. X-Clarnow-Signature is there only when the webhook has a signing secret.
Verify the signature
Section titled “Verify the signature”v1 is the hex HMAC-SHA256 of {t}.{raw body}, keyed with your signing secret — the same scheme Stripe uses. Because the timestamp is signed too, an old request can’t be replayed: reject any t more than a few minutes old.
Check it against the raw request body, before parsing the JSON. In Node.js:
const crypto = require('crypto')
function verify(rawBody, header, secret, toleranceSec = 300) { const parts = Object.fromEntries(header.split(',').map(kv => kv.split('=')))
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t)) if (!Number.isFinite(age) || age > toleranceSec) return false
const expected = crypto .createHmac('sha256', secret) .update(`${parts.t}.${rawBody}`) .digest('hex')
const given = Buffer.from(parts.v1 ?? '') return given.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), given)}Delivery and the log
Section titled “Delivery and the log”- One attempt per endpoint per response, with a 10-second timeout. Failed deliveries are not retried.
- Requests to several endpoints go out in parallel and never slow down the respondent.
- Recent deliveries under each webhook lists every attempt with its status code and time; click Refresh to update it. Attempts are kept for 30 days.
Data shared
Section titled “Data shared”| What | Where it goes | Why |
|---|---|---|
| The whole response: answers, files as 7-day links, score, ending, variables, UTM tags and other URL parameters, source and referring page, times | Your endpoint URL | The webhook itself |
What ClarNow stores about the webhook: the URL, the signing secret, the on/off switch, and a log of deliveries (time, status code, duration) kept for 30 days. They are deleted when you delete the webhook, permanently delete the form, or close your ClarNow account. Details are in the Privacy Policy.
Pause, edit or delete a webhook
Section titled “Pause, edit or delete a webhook”Open the form → Connect → Webhooks, and in the webhook’s row:
- Pause: turn Active off. Nothing is sent until you turn it back on; responses in between are not sent later.
- Edit: click the edit icon to change the URL, the switch or the signing secret. Your endpoint must use the new secret from the next request.
- Delete: open the webhook, click Delete Webhook and confirm. Its delivery log goes with it.
Zapier and Make connections are webhooks too, so they appear in this list as well.
Which ClarNow plan do I need for webhooks?
Any plan, including Free. A form can have as many webhooks as you like.
Are failed deliveries retried?
No. Each endpoint gets one attempt per response, with a 10-second timeout. The attempt is logged with its status code, and the response stays in ClarNow, where you can see and export it. If missing a response matters, have your endpoint answer fast and queue the work on its side.
Which status codes count as delivered?
Any 2xx or 3xx answer shows green in the delivery log. Anything else, a timeout or a connection error shows red; a delivery that got no answer at all is logged as ERR.
How do I avoid processing the same response twice?
Use the X-Clarnow-Event-Id header or the event_id field. It is the same for every endpoint of the form and unique per response.
Are partial or abandoned responses sent?
No. A webhook fires when a response is submitted — event type response.completed — and for test deliveries.
How do I get the uploaded files?
Each file in the payload has a url valid for 7 days. Download it within that time. If the form also sends files to Google Drive, download them right away — ClarNow removes its own copy once a file is in Drive.
Can I send to http:// or localhost?
Plain http:// works, but use https:// for anything with real data. localhost and 127.0.0.1 are refused; use a tunnel such as ngrok to test a local server.
Support
Section titled “Support”Email [email protected] or pick a case on the contact page — no account needed. We reply within two business days, usually within one. See also Support, the Privacy Policy and the Terms of Service.
Cookie preferences
Required for the site to work — security and your session. No tracking.