Getting Started with Webhooks

Two outbound paths — which one do you need?

• Webhook endpoints (this article) — the standalone per-site setup at Settings → Webhooks. POSTs every matching submission, optional field whitelist, signed payload, 3 retries on failure.
• Custom Webhook destination in Routes — the newer Route-based path. Same outbound POST, plus conditional rules ("only if AI score is Hot"), per-route body templates, and method choice (POST/PUT). See "Sending to a Custom Webhook" in the Destinations & integrations category.

What webhooks do

Webhooks let LeadToSheet POST a JSON payload to a URL you control every time a form submission is captured. You can use this to push leads into a CRM, trigger Zapier or Make automations, send Slack notifications, or fan out to any internal system.

Webhooks fire in real time, in addition to the Google Sheets sync - they don't replace it.

Adding a webhook endpoint

Webhook endpoints are configured per site. You'll find them under Settings → Webhooks for the site you want to wire up.

1. 1

   Open the site's Webhooks page

   From the sidebar, choose the site you want, click Settings, then open the Webhooks tab.

2. 2

   Add a new endpoint

   Click "Add Endpoint" to open the configuration form.

3. 3

   Enter the destination URL

   Paste the URL where LeadToSheet should POST submissions. It must be a public HTTP or HTTPS URL - HTTPS is strongly recommended for any production endpoint.

4. 4

   Choose an HTTP method

   POST, PUT, or PATCH are supported. POST is the right choice for most integrations.

5. 5

   Pick a form scope

   Choose "All forms" to send every submission on this site, or pick a specific form to scope the webhook to a single form.

6. 6

   (Optional) Add a field whitelist

   By default LeadToSheet sends every captured field. Enter a comma- or newline-separated list to send only specific field names (e.g. email, phone, company). Matching is case-sensitive against the field names as the SDK captured them — peek at a recent submission in the Leads table to copy the exact casing if you're unsure (e.g. "Email" vs "email" need to match exactly). Whitespace is trimmed and duplicates are dropped.

7. 7

   (Optional) Add custom headers

   Add any custom HTTP headers the receiving system requires, such as an API key or bearer token. LeadToSheet silently strips four reserved header names if you try to set them (content-type, x-webhook-id, x-webhook-signature, x-webhook-timestamp) so the signature, replay ID, and payload encoding cannot be tampered with from the endpoint config.

8. 8

   (Optional) Toggle metadata

   Leave "Include metadata" enabled to send UTM parameters, ad click IDs, and browser data alongside the submission. Disable it for a leaner payload.

9. 9

   Click Create Endpoint

   The endpoint becomes active immediately and will receive the next matching submission.

The webhook payload

Each delivery is a JSON POST body with an event of "submission.created". The full shape:

• event - always "submission.created" for live deliveries (or "submission.test" if you click Test on the endpoint)
• timestamp - ISO 8601 timestamp of the delivery
• submission - id, formId, fields (key/value object of captured fields), submittedAt, url
• form - id, fingerprint, formName, action
• client - id, name
• metadata (optional) - userAgent, utmSource/Medium/Campaign/Term/Content, gclid, fbclid, msclkid, ttclid, liFatId, language, platform, timezone, referrer

Verifying webhook signatures

Every webhook delivery is signed so your endpoint can confirm it really came from LeadToSheet. Three headers are sent on every request:

• X-Webhook-Signature - HMAC-SHA256 hex digest of the raw request body, signed with the endpoint's secret
• X-Webhook-Id - a unique ID for this delivery attempt
• X-Webhook-Timestamp - ISO 8601 timestamp of when the payload was generated

To verify, recompute the HMAC-SHA256 of the raw request body using your endpoint's secret and compare it to the X-Webhook-Signature header in constant time.

Retries and timeouts

If your endpoint doesn't respond within 10 seconds, or returns a non-2xx status, the delivery is marked failed and automatically retried.

• Up to 2 retry attempts after the first delivery (3 tries in total)
• A failed delivery is retried about 1 minute later, then about 5 minutes after that. A retry check runs every few minutes, so a retry can land a little later than planned.
• After the final attempt, the delivery is left in a failed state. The webhook itself is re-enabled and ready for the next submission.

Testing an endpoint

Use the Test button on any endpoint to send a sample payload. The test payload uses event "submission.test" and contains placeholder fields, so you can confirm your handler is reachable and your signature verification works without waiting for a real submission.

Editing, disabling, or removing endpoints

Each endpoint card has four actions on the right: a toggle, an edit (pencil) button, a test (send) button, and a delete (trash) button.

• Toggle — temporarily disable an endpoint without deleting it. Disabled endpoints stop receiving new deliveries immediately, and any deliveries already queued are skipped at send time.
• Edit (pencil) — change the URL, method, form scope, field whitelist, custom headers, or metadata flag in place. The signing secret is preserved across edits so your receiver does not need to rotate.
• Test (send) — fires a one-off submission.test delivery (see the Testing an endpoint section above).
• Delete (trash) — remove the endpoint and its delivery history permanently. There is no soft-delete or undo.

Related