Include metadata field in `lead.created` and `sale.created` webhook payload #2854

devkiran · 2025-09-17T05:18:07Z

Summary by CodeRabbit

New Features
- Webhook payloads for lead.created and sale now include a top-level nullable metadata object.
- Sale webhook metadata is delivered as an object rather than a JSON string.
Documentation
- Sample lead.created and sale-created events updated to show the metadata field.
Tests
- Webhook schemas updated to validate the new optional metadata field for lead and sale events.

vercel · 2025-09-17T05:18:11Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
dub	Ready	Preview	Sep 17, 2025 9:37pm

coderabbitai · 2025-09-17T05:18:14Z

Walkthrough

Adds a nullable top-level metadata field to lead and sale webhook payloads: track-lead/track-sale now pass metadata through, transform functions include metadata in parsed payloads, schemas accept metadata as z.record(z.unknown()).nullable().default(null), and sample events are updated.

Changes

Cohort / File(s)	Summary
Conversion tracking APIs `apps/web/lib/api/conversions/track-lead.ts`, `apps/web/lib/api/conversions/track-sale.ts`	Pass the incoming `metadata` through into the webhook payload construction; `track-sale` now passes metadata as an object rather than a JSON string.
Webhook transform & schemas `apps/web/lib/webhook/transform.ts`, `apps/web/lib/webhook/schemas.ts`	`transformLeadEventData` and `transformSaleEventData` include `metadata: ... ?? null` in the objects parsed; `leadWebhookEventSchema` and `saleWebhookEventSchema` gain `metadata: z.record(z.unknown()).nullable().default(null)`.
Sample events `apps/web/lib/webhook/sample-events/lead-created.json`, `apps/web/lib/webhook/sample-events/sale-created.json`	Add root-level `"metadata": null` to the sample lead and sale created event JSON files.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Client
  participant API as Conversions API
  participant Xform as Transform (lead/sale)
  participant Schema as Webhook Schema
  participant WH as Webhook Dispatcher
  participant Sub as Subscriber

  Client->>API: Track Lead/Sale (payload includes metadata)
  API->>Xform: Build event object { ..., metadata }
  Xform->>Schema: Parse/validate event (metadata: object | null)
  Schema-->>Xform: Validated event
  Xform-->>WH: Emit webhook { ..., metadata }
  WH-->>Sub: Deliver webhook
  Note over Xform,Schema: New nullable `metadata` field flows through validation and dispatch

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Add noop response to /track/lead (instead of error) #2827 — Modifies apps/web/lib/api/conversions/track-lead.ts; related by changes to the lead tracking flow.
Allow automatic lead event creation in track/sale #2818 — Also propagates top-level metadata through tracking, transform, and schema code paths.
Add lead params to /track/sale/client #2822 — Adjusts how sale/lead metadata is passed through /track/sale routes so metadata reaches the tracking layer.

Poem

I nibble bytes beneath the moonlight,
A metadata carrot tucked in tight,
Leads and sales now hop along,
Payloads humming a merrier song,
Tiny rabbit cheers — events take flight! 🥕🐇

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly and accurately describes the primary change — adding a metadata field to the lead.created and sale.created webhook payloads — and matches the modifications to schemas, transformers, and sample events in the changeset.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch lead-created-event-metadata

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (6)

apps/web/lib/webhook/sample-events/lead-created.json (2)
77-79: Add a concrete metadata example for clarity

Including a small object (instead of null) better illustrates shape and keys. Optional but helpful for integrators.

Example:
"metadata": { "plan": "pro", "source": "newsletter" }
1-80: Consider using a documentation-reserved IP in samples

The sample shows a real-looking IP. Prefer 203.0.113.0/24, 198.51.100.0/24, or 192.0.2.0/24 ranges in examples.
apps/web/lib/api/conversions/track-sale.ts (1)

424-435: Minor: add a comment to avoid future confusion

saleData.metadata remains stringified for Tinybird ingestion, while webhook uses the raw object via the later spread. A brief comment near the saleData construction would prevent regressions.

apps/web/lib/api/conversions/track-lead.ts (1)

160-171: Verify metadata serialization consistency across paths

You stringify metadata for Tinybird ingestion elsewhere; here you forward the raw object for the webhook. That’s fine—just ensure docs note: storage = string, webhook = object.

apps/web/lib/webhook/schemas.ts (2)

26-26: Schema addition looks good; add a brief description

metadata: z.record(z.unknown()).nullable().default(null) is fine. Consider .describe("Arbitrary user-provided key-value metadata") to improve OpenAPI.

35-35: Mirror description on sale schema and confirm OpenAPI includes it

Ensure the generated spec surfaces metadata under both lead.created and sale.created events.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between df2e56e and 2b7c9a1.

📒 Files selected for processing (5)

apps/web/lib/api/conversions/track-lead.ts (1 hunks)
apps/web/lib/api/conversions/track-sale.ts (1 hunks)
apps/web/lib/webhook/sample-events/lead-created.json (1 hunks)
apps/web/lib/webhook/schemas.ts (2 hunks)
apps/web/lib/webhook/transform.ts (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

GitHub Check: Vade Review
GitHub Check: build

🔇 Additional comments (4)

apps/web/lib/api/conversions/track-sale.ts (1)

539-540: Passing raw object metadata to webhook is correct; confirm response schema parity

This overrides the stringified metadata in saleData for the webhook path—intended and good. Please confirm trackSaleResponseSchema.sss accepts metadata as an object to match the response you return.

If it doesn’t, update the response schema or serialize consistently.

apps/web/lib/api/conversions/track-lead.ts (1)

325-333: Good: metadata now included in lead webhook payload

This matches the updated schema and transform. No issues spotted.

apps/web/lib/webhook/transform.ts (2)

75-78: LGTM: lead metadata passthrough

The null defaulting is correct and aligns with the schema.

104-107: LGTM: sale metadata passthrough

Correctly prefers the object provided by callers (over any stringified value upstream).

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

apps/web/lib/webhook/sample-events/sale-created.json (1)
83-84: Consider a non-null example to clarify expected usage.

Showing a minimal populated object improves DX and sets expectations for nesting/key types.
-  "metadata": null
+  "metadata": {
+    "source": "checkout",
+    "coupon": "WELCOME10",
+    "extra": { "plan": "pro", "seats": 5 }
+  }

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2b7c9a1 and 31db338.

📒 Files selected for processing (1)

apps/web/lib/webhook/sample-events/sale-created.json (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

GitHub Check: Vade Review
GitHub Check: build

🔇 Additional comments (2)

apps/web/lib/webhook/sample-events/sale-created.json (2)

83-84: LGTM: metadata field added and JSON stays valid.

The comma after the sale object and the root-level "metadata": null are correct. No JSON trailing-comma issues.

83-84: Verify event name and parallel sample updates.

Confirm that eventName "Subscription" is the intended value for sale.created consumers.

Ensure lead-created.json carries the same top-level metadata shape and null default.

apps/web/lib/webhook/transform.ts

devkiran added 2 commits September 17, 2025 10:35

Include lead metadata field in "lead.created" webhook payload

8ecee2e

Add metadata field to sale webhook event schema and transform function

2b7c9a1

devkiran changed the title ~~Include lead metadata field in lead.created and sale.created webhook payload~~ Include metadata field in lead.created and sale.created webhook payload Sep 17, 2025

vercel bot deployed to Preview September 17, 2025 05:22 View deployment

coderabbitai bot reviewed Sep 17, 2025

View reviewed changes

Update sale-created.json

31db338

coderabbitai bot reviewed Sep 17, 2025

View reviewed changes

vercel bot deployed to Preview September 17, 2025 05:35 View deployment

vercel bot reviewed Sep 17, 2025

View reviewed changes

apps/web/lib/webhook/transform.ts Show resolved Hide resolved

Merge branch 'main' into lead-created-event-metadata

0dbd47b

vercel bot deployed to Preview September 17, 2025 21:37 View deployment

steven-tey approved these changes Sep 17, 2025

View reviewed changes

steven-tey merged commit 953691f into main Sep 17, 2025
9 checks passed

steven-tey deleted the lead-created-event-metadata branch September 17, 2025 22:12

coderabbitai bot mentioned this pull request Sep 19, 2025

Fix the metadata property in webhook payload #2861

Merged

coderabbitai bot mentioned this pull request Oct 18, 2025

Leverage clickIdCache to reduce load on Tinybird #2981

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Include metadata field in `lead.created` and `sale.created` webhook payload #2854

Include metadata field in `lead.created` and `sale.created` webhook payload #2854

Uh oh!

devkiran commented Sep 17, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

vercel bot commented Sep 17, 2025 •

edited

Loading

Uh oh!

coderabbitai bot commented Sep 17, 2025 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Include metadata field in lead.created and sale.created webhook payload #2854

Include metadata field in lead.created and sale.created webhook payload #2854

Uh oh!

Conversation

devkiran commented Sep 17, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

vercel bot commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Poem

Pre-merge checks and finishing touches

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Include metadata field in `lead.created` and `sale.created` webhook payload #2854

Include metadata field in `lead.created` and `sale.created` webhook payload #2854

devkiran commented Sep 17, 2025 •

edited by coderabbitai bot

Loading

vercel bot commented Sep 17, 2025 •

edited

Loading

coderabbitai bot commented Sep 17, 2025 •

edited

Loading