Custom Webhooks

Send conversion events to any HTTP endpoint — useful for connecting to internal systems, CRMs, or platforms that ioZen doesn't have a native integration for.

Setup

Open your Intake Bot → Settings → Marketing & Attribution
Toggle Webhook on
Enter the Webhook URL (must accept POST requests)
Optionally add Custom Headers (one per line, format: Header-Name: value)
The settings auto-save

Payload Format

ioZen sends a JSON POST request with this structure:

{
  "event_name": "Lead",
  "event_id": "unique-event-id",
  "event_time": "2026-03-05T12:00:00.000Z",
  "event_time_unix": 1772827200,
  "source": "iozen",
  "action_source": "website",
  "user_data": {
    "email": "user@example.com",
    "phone": "+1234567890",
    "first_name": "Jane",
    "last_name": "Doe",
    "external_id": "submission-id"
  },
  "custom_data": {
    "value": 100,
    "currency": "USD",
    "content_name": "Lead"
  },
  "source_url": "https://example.com/landing-page"
}

Headers

Every request includes these headers:

Header	Description
`Content-Type`	`application/json`
`X-IoZen-Event-Id`	Unique event ID for deduplication
`X-IoZen-Event-Name`	Event name (e.g., `Lead`, `FieldConversion`)

Plus any custom headers you configure.

Test Connection

Click Test Connection to send a test event. The test payload includes X-IoZen-Test: true header so your endpoint can distinguish test from real events.

Troubleshooting

Error	Cause	Fix
HTTP 401	Authentication failed	Check your Authorization header value in Custom Headers.
HTTP 403	Access denied	Verify your webhook URL and any required API keys.
HTTP 404	Endpoint not found	Verify the webhook URL is correct and accepts POST requests.
HTTP 500	Server error	Check the receiving server logs for details.
Request timed out	Endpoint didn't respond in 30s	Ensure your server responds within 30 seconds.

Best Practices

Return 200 quickly — Process events asynchronously if possible. ioZen waits up to 30 seconds for a response.
Use the event ID for deduplication — The X-IoZen-Event-Id header and event_id field are unique per event. Use them to avoid processing duplicates.
Verify the source — Check for the X-IoZen-Event-Id header to confirm requests come from ioZen.