Skip to main content

@zyphe-sdk/node

Install the package:

pnpm add @zyphe-sdk/node

1. Webhook Signature Verification​

This package provides the core webhook signature verification logic for Zyphe. It enables secure verification of incoming webhook requests in Node.js using HMAC-SHA256 signatures.

Basic Usage​

import { verifyWebhookSignatureHeader } from '@zyphe-sdk/node'

const secretHex = '<your-hex-encoded-secret>'
const rawBodyString = '...' // The raw request body as a string
const signatureHeader = 't=1234567890,v0=abcdef...' // The signature header from the webhook

const isValid = verifyWebhookSignatureHeader(secretHex, rawBodyString, signatureHeader)
if (isValid) {
  // Signature is valid
} else {
  // Signature is invalid
}
  • secretHex: The hex-encoded secret key used to sign the webhook.
  • rawBodyString: The raw request body as a string (must match exactly what was sent).
  • signatureHeader: The signature header string, e.g. t=1234567890,v0=abcdef....
  • Returns: true if the signature is valid, or false otherwise.

Advanced Utilities​

  • parseSignatureHeader(signatureHeader) – Parse the signature header into timestamp and signature.
  • hexToBytes(hex) / bufferToHex(buffer) – Convert between hex and bytes.
  • timingSafeEqual(a, b) – Constant-time string comparison.
  • Error codes/messages for robust error handling.

2. Verification Session Management​

You can programmatically create verification sessions and construct user-facing URLs for onboarding flows.

Create a Verification Session​

import { createVerificationSession } from '@zyphe-sdk/node'

const response = await createVerificationSession(
  {
    email: 'user@example.com', // required
    flowId: '<flowId>', // required
    flowStepId: '<flowStepId>', // required
    isSandbox: false, // required
    customData: {
      // optional
      walletAddress: '0x123...',
      // ...any extra data you want to pass
    },
  },
  {
    apiKey: '<your-api-key>',
    environment: 'staging', // or "production", "local"
    handoffBaseUrl: 'https://your-app.com', // optional
    primaryColor: '#000000', // optional
    secondaryColor: '#ffffff', // optional
    isFullscreen: true, // optional
  },
)
  • customData (optional): Pass any extra data you want to associate with the verification session. This will be available in the webhook payload and session data.
  • The function returns a Promise resolving to the API response. Handle errors as needed (e.g., try/catch or checking for error fields).

Construct a Verification Session URL​

import { constructVerificationSessionUrl } from '@zyphe-sdk/node'

const url = constructVerificationSessionUrl({
  flowParams: {
    flowId: '...',
    flowStepId: '...',
    email: 'user@example.com',
    product: 'kyc', // or "kyb" if supported
    isSandbox: false,
    customData: { walletAddress: '0x123...' }, // optional
  },
  verificationSession: response.data, // from createVerificationSession
  opts: {
    apiKey: '<your-api-key>',
    environment: 'staging',
    handoffBaseUrl: 'https://your-app.com', // optional
    primaryColor: '#000000', // optional
    secondaryColor: '#ffffff', // optional
    isFullscreen: true, // optional
  },
})
  • The constructed URL includes all relevant parameters and can be used to embed or redirect users to the verification flow.
  • Optional fields (like handoffBaseUrl, primaryColor, etc.) will be appended as query parameters if provided.

Types​

  • InitializeZypheFlowParams: Parameters for initializing a verification flow.
  • SDKOptions: Configuration for the SDK.
  • SdkCreateVerificationRequestResponse: API response type for session creation.

Error Handling​

  • If session creation fails, the function may throw or return an error object depending on usage context. Always check for errors and handle them appropriately.
  • Example:
try {
  const response = await createVerificationSession(...);
  if (response.error) {
    // Handle error
    console.error(response.error);
  } else {
    // Success
  }
} catch (err) {
  // Handle thrown errors (e.g., network issues)
  console.error(err);
}

3. Types and Configuration​

  • InitializeZypheFlowParams, SDKOptions, SdkCreateVerificationRequestResponse – for type-safe integration.
  • Environments, EnvironmentConfigs, API_KEY_HEADER – for environment and API configuration.