Relevant source files

The following files were used as context for generating this wiki page: - [src/webhook/errors.ts](https://github.com/primitivedotdev/sdk-node/blob/main/src/webhook/errors.ts) - [src/webhook/index.ts](https://github.com/primitivedotdev/sdk-node/blob/main/src/webhook/index.ts) - [src/webhook/signing.ts](https://github.com/primitivedotdev/sdk-node/blob/main/src/webhook/signing.ts) - [src/zod.ts](https://github.com/primitivedotdev/sdk-node/blob/main/src/zod.ts) - [tests/webhook/index.test.ts](https://github.com/primitivedotdev/sdk-node/blob/main/tests/webhook/index.test.ts)

# Webhook Error Handling The Primitive SDK provides a structured, multi-layered approach to handling errors that occur during the webhook lifecycle. This system ensures that developers can distinguish between security failures, malformed payloads, and schema violations through a hierarchy of custom error classes and descriptive error codes. The error handling architecture is designed to provide actionable guidance via a `suggestion` property on every error instance, helping developers quickly resolve common integration issues such as clock skew, incorrect secrets, or re-serialized JSON bodies. Sources: [src/webhook/errors.ts:107-135](), [src/webhook/index.ts:1-25]() ## Error Hierarchy and Base Classes All webhook-related errors in the SDK inherit from a central abstract class, `PrimitiveWebhookError`. This base class extends the native JavaScript `Error` and enforces the implementation of programmatic codes and actionable suggestions. ```mermaid classDiagram class Error { <> } class PrimitiveWebhookError { +WebhookErrorCode code +string suggestion +toString() +toJSON() } class WebhookVerificationError { +WebhookVerificationErrorCode code } class WebhookPayloadError { +WebhookPayloadErrorCode code +Error cause } class WebhookValidationError { +string field +ZodError zodError +number additionalErrorCount } class RawEmailDecodeError { +RawEmailDecodeErrorCode code } Error <|-- PrimitiveWebhookError PrimitiveWebhookError <|-- WebhookVerificationError PrimitiveWebhookError <|-- WebhookPayloadError PrimitiveWebhookError <|-- WebhookValidationError PrimitiveWebhookError <|-- RawEmailDecodeError ``` The diagram above shows the inheritance structure of the custom error classes used by the SDK. Sources: [src/webhook/errors.ts:130-264]() ### Core Error Categories | Error Class | Purpose | Primary Triggers | | :--- | :--- | :--- | | `WebhookVerificationError` | Security and integrity failures. | Missing signatures, mismatched HMAC, or expired timestamps. | | `WebhookPayloadError` | Issues with the physical structure of the request. | Invalid JSON, null bodies, or incorrect HTTP encoding. | | `WebhookValidationError` | Violations of the expected data schema. | Missing required fields or incorrect data types (via Zod). | | `RawEmailDecodeError` | Failures during post-processing of content. | Hash mismatch during decoding or accessing non-inline content. | Sources: [src/webhook/errors.ts:15-103]() ## Verification Errors Verification errors occur during the first stage of the `handleWebhook` process. The SDK validates the `Primitive-Signature` header against the raw request body using HMAC-SHA256. ```mermaid flowchart TD Start[Check Signature Header] -->|Missing/Malformed| E1[INVALID_SIGNATURE_HEADER] Start -->|Valid Format| Timestamp{Check Timestamp} Timestamp -->|Too Old/Future| E2[TIMESTAMP_OUT_OF_RANGE] Timestamp -->|In Range| HMAC[Compute & Compare HMAC] HMAC -->|Mismatch| E3[SIGNATURE_MISMATCH] HMAC -->|Match| Success[Proceed to Parsing] ``` This flow illustrates the sequence of security checks that can trigger a `WebhookVerificationError`. Sources: [src/webhook/signing.ts:182-255]() ### Common Verification Codes * **SIGNATURE_MISMATCH**: Occurs when the secret is incorrect or if the body was modified (e.g., re-serialized by a framework). The SDK specifically detects "pretty-printed" JSON to provide a hint about re-serialization. * **TIMESTAMP_OUT_OF_RANGE**: Triggered if the webhook is older than the `toleranceSeconds` (default 300s) or too far in the future, protecting against replay attacks. * **MISSING_SECRET**: Thrown if the developer fails to provide the webhook secret to the verification function. Sources: [src/webhook/errors.ts:15-36](), [src/webhook/signing.ts:257-272]() ## Payload and Parsing Errors Payload errors are thrown when the SDK cannot interpret the request as a valid webhook object. This often happens before full schema validation. | Code | Description | Suggestion | | :--- | :--- | :--- | | `JSON_PARSE_FAILED` | The body is not valid JSON. | Check raw body content and Content-Type. | | `INVALID_ENCODING` | The body is not UTF-8. | Ensure the web server is not altering bytes. | | `PAYLOAD_IS_ARRAY` | Received `[]` instead of `{}`. | Primitive webhooks are single objects. | | `PAYLOAD_MISSING_EVENT` | No `event` field found. | Verify the payload is a valid Primitive event. | Sources: [src/webhook/errors.ts:41-80]() ## Schema Validation Errors The `WebhookValidationError` is unique because it wraps [Zod](https://zod.dev) validation results. It provides high-granularity feedback about which specific field failed validation. ### Error Formatting When a validation fails, the SDK formats the Zod error into a human-readable structure: 1. **Field Path**: Identifies the exact location of the error (e.g., `email.headers.from`). 2. **Field Description**: Maps technical paths to readable names (e.g., "From header"). 3. **Actionable Suggestion**: Provides specific fixes, such as "Don't quote numeric values in JSON" for type mismatches. Sources: [src/zod.ts:233-311](), [src/webhook/errors.ts:208-245]() ### Validation Flow ```mermaid sequenceDiagram participant SDK as SDK (handleWebhook) participant Zod as Zod Schema participant FE as Error Formatter SDK->>Zod: safeParse(payload) Zod-->>SDK: error (ZodError) SDK->>FE: formatZodError(error) FE-->>SDK: { field, message, suggestion } SDK--xUser: throw WebhookValidationError ``` The sequence of transforming a raw Zod error into a developer-friendly `WebhookValidationError`. Sources: [src/zod.ts:403-415](), [src/webhook/index.ts:315-325]() ## Raw Email Decoding Errors If a developer attempts to use `decodeRawEmail()` on an event where the raw content was excluded (due to size limits), the SDK throws a `RawEmailDecodeError`. * **NOT_INCLUDED**: Thrown when the email exceeds the `max_inline_bytes` threshold. The error suggestion directs the user to the `download.url`. * **HASH_MISMATCH**: Triggered if the SHA-256 hash of the decoded base64 data (or downloaded binary) does not match the `sha256` field in the webhook payload, indicating potential corruption. Sources: [src/webhook/errors.ts:85-97](), [src/webhook/index.ts:553-596]() ## Summary of Programmatic Usage Developers are encouraged to catch the base `PrimitiveWebhookError` to handle all SDK-related issues in a single block while utilizing the `code` property for specific logic. ```typescript try { const event = handleWebhook({ body, headers, secret }); } catch (err) { if (err instanceof PrimitiveWebhookError) { // [SIGNATURE_MISMATCH] Signature doesn't match... console.error(`[${err.code}] ${err.message}`); console.error(`Suggestion: ${err.suggestion}`); } } ``` Sources: [src/webhook/errors.ts:110-125]()