parse_error

Summary

What caused it

The signature check passed — the body is authentically from the provider — but hooksentinel couldn't parse it into a usable event. This happens after verification, so it's a distinct failure mode from the signature-related codes: the request is genuine, but its content isn't what the provider adapter expected to receive.

Common causes:

• The body isn't valid JSON at all. Rare for a legitimate provider request, but possible if a provider sends a non-JSON payload type you haven't accounted for (e.g. Twilio's default webhook format is form-encoded, not JSON — see the fix below).
• The JSON is valid but missing fields the provider adapter requires — e.g. no type field where the adapter expects one to route the event.
• A provider changed its payload shape in a way the installed version of hooksentinel doesn't yet know about — check for a newer release on the changelog.

The fix

For Twilio specifically, confirm you're sending the right content type. Twilio's webhooks are application/x-www-form-urlencoded by default, not JSON — the twilio() provider adapter parses form-encoded bodies natively, so this is usually only an issue if a proxy or a manual test sends JSON instead:

import { twilio } from '@hooksentinel/core';

twilio({
  authToken: process.env.TWILIO_AUTH_TOKEN!,
  url: 'https://api.example.com/webhooks/twilio',
});
// expects application/x-www-form-urlencoded — this is handled for you,
// but a manual curl test with `-H "Content-Type: application/json"` will
// produce parse_error even with a correct signature

Log the raw body to see exactly what's failing to parse:

onError: async (error, ctx) => {
  if (error.code === 'parse_error') {
    logger.error('parse_error', { provider: ctx.provider, eventId: ctx.eventId });
    // avoid logging the full raw body in production if it may contain PII
  }
},

Check for a hooksentinel version mismatch against the provider's current payload format — providers occasionally add required fields or restructure nested objects. If the body is valid JSON but doesn't match a documented event shape, check the changelog for a newer release before assuming it's an application bug.