payload_too_large

Summary

What caused it

The raw request body exceeded maxBodyBytes, which defaults to 1,000,000 bytes (1 MB). This limit exists so an oversized or malicious request body can't tie up memory or CPU computing a signature over an unbounded payload before verification has even had a chance to reject it.

Most provider events are a few KB. This error usually means one of:

• A provider event that's genuinely larger than 1 MB — GitHub's push events with a large number of commits, or Shopify bulk operation payloads, can occasionally exceed the default.
• The wrong content type reaching the route — if a non-webhook request (e.g. a large file upload accidentally routed to the webhook path) hits the endpoint.
• maxBodyBytes set too low for a provider you've configured it for deliberately.

The fix

If the provider's payload is legitimately large, raise the limit for that handler:

import { createWebhookHandler, github } from '@hooksentinel/core';

const githubWebhook = createWebhookHandler({
  provider: github({ secret: process.env.GITHUB_WEBHOOK_SECRET! }),
  maxBodyBytes: 5_000_000, // 5 MB
  onEvent: async (event) => { /* ... */ },
});

Check the provider's own documented maximum payload size before raising this — there's no benefit to setting maxBodyBytes higher than what the provider will ever actually send, and doing so only increases the amount of untrusted data your server will buffer per request.

If you're seeing this from unexpected traffic, confirm nothing else is routed to the same path — webhook routes should only ever receive requests from the provider's IP ranges or with the provider's headers, and a generic body size cap on the route (independent of hooksentinel) is a reasonable extra layer of defense at the framework or proxy level.