Webhooks | payload-posthog

payloadPosthog({
  apiKey: process.env.POSTHOG_API_KEY!,
  webhooks: {
    secret: process.env.POSTHOG_WEBHOOK_SECRET, // HMAC-SHA256 over the raw body; omit to skip verification
    path: '/posthog/webhook', // default
    signatureHeader: 'x-posthog-signature', // default
    handler: async ({ payload: webhookPayload, req }) => {
      await req.payload.create({ collection: 'posthog-events', data: webhookPayload })
      return Response.json({ received: true })
    },
  },
})

There's no default handler — inbound webhook payloads are inherently application-specific (survey responses, experiment results, custom destinations), so you provide the logic. The plugin handles signature verification (when secret is set) and JSON parsing before calling your handler; an invalid signature short-circuits to a 401 before your handler ever runs.

Omitting secret skips verification entirely — fine for local development, not recommended in production.