Configure webhook to receive leads

What is a webhook?#

A webhook is the endpoint that automatically receives your lead data. When a form is filled out on your landing page, the data is sent via HTTP POST to the Zero Bad Leads webhook URL.

Step by step#

Create an API Key

Go to Receive Leads → API Keys in the sidebar. Click "New API Key", give it a descriptive name (e.g., "Landing Page Form") and copy the generated key.

The API Key is only displayed once. Save it in a secure location.

Copy the webhook URL

The webhook URL follows this format:

https://ctmhfalurdthlddaprfd.supabase.co/functions/v1/webhook-receiver

You will use it when configuring your form.

Configure your form

In your form or platform, set up the webhook with:

URL: the URL copied in the previous step
Method: POST
Header: x-api-key: YOUR_API_KEY
Content-Type: application/json

The request body should be a JSON with the lead fields:

{
  "email": "john@company.com",
  "name": "John Smith",
  "phone": "+1 (555) 123-4567",
  "company": "Company XYZ"
}

Test the webhook

Send a test lead through your form and check the Leads page to see if it appeared. The initial status will be "new" and after qualification it will change to "qualified" or "skipped".

Automatically recognized fields#

Zero Bad Leads recognizes over 100 field name variations in Portuguese, English, and Spanish. For example:

Field	Recognized aliases
Email	`email`, `e-mail`, `email_address`, `correo`
Phone	`telefone`, `phone`, `celular`, `whatsapp`, `mobile`
Name	`nome`, `name`, `primeiro_nome`, `first_name`
Company	`empresa`, `company`, `razao_social`, `company_name`

Fields that are not automatically recognized are saved as custom fields, without consuming additional mapping.

Webhook limits#

Limit	Value	What happens if exceeded
Payload size	1 MB per request	Response `HTTP 413 Payload Too Large`
Rate limit	60 requests per minute, per API Key	Response `HTTP 429 Too Many Requests` (retry after 60s)
Deduplication window	24h by default (configurable from 1 to 168h)	Duplicate lead is dropped, response `200` with `duplicate: true`

Leads without an email and without a phone do not go through deduplication — every submission creates a new lead. This is intentional for B2B without direct contact.

Troubleshooting#

The lead doesn't appear on the platform?

Check that the API Key is correct in the x-api-key header
Confirm that the Content-Type is application/json
Check the logs under Logs in the sidebar for detailed errors

I received HTTP 413 Payload Too Large?

Your payload exceeded 1 MB. Reduce the JSON sent (remove unused fields, split into multiple requests).

I received HTTP 429 Too Many Requests?

You exceeded 60 requests/min per API Key. Wait 60 seconds and try again, or create a second API Key to split traffic.

I received HTTP 401 Unauthorized?

API Key invalid or revoked. Create a new one under Receive Leads → API Keys.

I received HTTP 402 Payment Required?

Your subscription is paused, canceled, or inactive. Reactivate it under Settings → Billing.