chore: webhook payload must be an array

[arcoraven]

[SDK] Fix: Require webhook payload to be an array

Notes for the reviewer

This PR updates the webhook event payload type to be an array of records instead of a single record. It also adds validation to ensure the payload array is not empty.

How to test

Verify that webhook events with empty payloads are rejected, and that the type definition correctly requires an array of records.

---

PR-Codex overview

This PR focuses on enforcing that the payload in webhook events must be an array and cannot be empty, enhancing the validation of webhook data.

Detailed summary

• Updated the createdAt property in the WebhookEvent interface to be optional.
• Changed the payload property to be an array of Record<string, unknown> and added a requirement that it must not be empty.
• Added an assertion in the sendEvents method to check that payload length is greater than 0.

✨ Ask PR-Codex anything about this PR by commenting with /codex {your question}

Summary by CodeRabbit

• Chores

  • Webhook payloads are now required to be non-empty arrays, improving consistency in webhook event handling.

• New Features

  • Webhook events now include an optional timestamp indicating when the event was triggered.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
docs-v2	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 26, 2025 10:47am
nebula	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 26, 2025 10:47am
thirdweb_playground	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 26, 2025 10:47am
thirdweb-www	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 26, 2025 10:47am
wallet-ui	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 26, 2025 10:47am

[changeset-bot]

🦋 Changeset detected

Latest commit: 9f8552d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@thirdweb-dev/service-utils	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Walkthrough

The changes update the WebhookEvent interface to require the payload property as a non-empty array of records and introduce an optional createdAt timestamp. Additionally, the WebhookEventProducer.sendEvents method now asserts that each event's payload array is not empty before processing.

Changes

File(s)	Change Summary
.changeset/huge-eggs-drop.md	Added a changeset describing the enforcement of webhook payloads as arrays for @thirdweb-dev/service-utils.
packages/service-utils/src/node/webhookProducer.ts	Updated WebhookEvent interface: payload is now a non-empty array; added optional createdAt. Modified sendEvents to assert non-empty payloads.

Sequence Diagram(s)

sequenceDiagram
    participant Caller
    participant WebhookEventProducer

    Caller->>WebhookEventProducer: sendEvents(events)
    loop For each event
        WebhookEventProducer->>WebhookEventProducer: Assert event.payload is a non-empty array
        alt Payload is empty
            WebhookEventProducer-->>Caller: Throw error
        else Payload is valid
            WebhookEventProducer->>WebhookEventProducer: Proceed with validation and sending
        end
    end

Loading

Possibly related PRs

• feat: add webhook producer to service-utils #7439: Introduced the initial WebhookEventProducer class and interface, which are directly modified in this PR to enforce array payloads and add the createdAt field.

---

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0345492 and 9f8552d.

📒 Files selected for processing (2)

• .changeset/huge-eggs-drop.md (1 hunks)
• packages/service-utils/src/node/webhookProducer.ts (2 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

`**/*.@(ts|tsx)`: Accept a typed 'props' object and export a named function (e.g...

**/*.@(ts|tsx): Accept a typed 'props' object and export a named function (e.g., export function MyComponent()).
Combine class names via 'cn', expose 'className' prop if useful.
Reuse core UI primitives; avoid re-implementing buttons, cards, modals.
Local state or effects live inside; data fetching happens in hooks.
Merge class names with 'cn' from '@/lib/utils' to keep conditional logic readable.
Stick to design-tokens: background ('bg-card'), borders ('border-border'), muted text ('text-muted-foreground') etc.
Use the 'container' class with a 'max-w-7xl' cap for page width consistency.
Spacing utilities ('px-', 'py-', 'gap-*') are preferred over custom margins.
Responsive helpers follow mobile-first ('max-sm', 'md', 'lg', 'xl').
Never hard-code colors – always go through Tailwind variables.
Tailwind CSS is the styling system – avoid inline styles or CSS modules.
Prefix files with 'import "server-only";' so they never end up in the client bundle (for server-only code).

📄 Source: CodeRabbit Inference Engine (.cursor/rules/dashboard.mdc)

List of files the instruction was applied to:

• packages/service-utils/src/node/webhookProducer.ts

⏰ Context from checks skipped due to timeout of 90000ms (2)

• GitHub Check: Size
• GitHub Check: Analyze (javascript)

🔇 Additional comments (3)

packages/service-utils/src/node/webhookProducer.ts (2)

45-45: LGTM: Runtime validation enhances data integrity.

The assertion correctly validates that the payload array is not empty, providing a clear fail-fast mechanism with a descriptive error message. This aligns well with the interface documentation and ensures data integrity at runtime.

---

9-16: Breaking change: Verify impact on existing consumers.

The change from Record<string, unknown> to Record<string, unknown>[] for the payload property is a breaking change that will affect existing code. While the JSDoc documentation is excellent and clearly states the requirements, ensure all existing consumers of this interface are updated accordingly.

#!/bin/bash
# Description: Find all usages of WebhookEvent interface to assess breaking change impact
# Expected: All usages should be updated to handle array payloads

echo "Searching for WebhookEvent interface usage..."
rg -A 3 -B 3 "WebhookEvent" --type ts

echo -e "\nSearching for payload property access..."
rg -A 2 -B 2 "\.payload" --type ts

echo -e "\nSearching for files importing webhookProducer..."
rg -l "webhookProducer|WebhookEvent" --type ts

.changeset/huge-eggs-drop.md (1)

1-5: Consider if this should be a major version change.

While the description accurately reflects the change, this appears to be a breaking change (payload type changed from single object to array) which typically warrants a major version bump rather than a patch. Consider whether this should be marked as a major version change to properly communicate the breaking nature to consumers.

What is the semantic versioning convention for breaking changes in TypeScript interfaces?

✨ Finishing Touches

• 📝 Generate Docstrings

---

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[arcoraven]

• chore: webhook payload must be an array #7444 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• merge-queue - adds this PR to the back of the merge queue
• hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 51.92%. Comparing base (0345492) to head (9f8552d).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #7444   +/-   ##
=======================================
  Coverage   51.92%   51.92%           
=======================================
  Files         947      947           
  Lines       63875    63875           
  Branches     4214     4214           
=======================================
  Hits        33166    33166           
  Misses      30603    30603           
  Partials      106      106           

Flag	Coverage Δ
packages	51.92% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

size-limit report 📦

Path	Size	Loading time (3g)	Running time (snapdragon)	Total time
thirdweb (esm)	62.75 KB (0%)	1.3 s (0%)	247 ms (+28.3% 🔺)	1.6 s
thirdweb (cjs)	351.77 KB (0%)	7.1 s (0%)	1.6 s (-0.35% 🔽)	8.7 s
thirdweb (minimal + tree-shaking)	5.72 KB (0%)	115 ms (0%)	84 ms (+467.5% 🔺)	198 ms
thirdweb/chains (tree-shaking)	530 B (0%)	11 ms (0%)	54 ms (+1438.76% 🔺)	64 ms
thirdweb/react (minimal + tree-shaking)	19.61 KB (0%)	393 ms (0%)	146 ms (+376.57% 🔺)	538 ms