Use the SDK webhook helpers to verify inbound Kyshi webhooks before trusting the payload.

Verify Webhook Signatures

Verify against the raw request body and the X-Kyshi-Signature header.

const event = kyshi.webhooks.constructEvent(
  rawRequestBody,
  request.headers['x-kyshi-signature'],
  process.env.KYSHI_WEBHOOK_SECRET!,
);

If verification fails, constructEvent throws an error. Your endpoint should return a 400 response for invalid signatures.

Webhook Operations

The SDK also exposes webhook inspection and replay methods.

const events = await kyshi.webhooks.listEvents({
  limit: 20,
});

await kyshi.webhooks.replayEvent('event-id');

These methods use the same SDK secretKey as other API calls. The integrating business must provide a Kyshi API key with access to those webhook operations routes.

Error Handling

The SDK exports error classes you can use in application code.

import {
  KyshiApiError,
  KyshiAuthenticationError,
  KyshiNetworkError,
  KyshiTimeoutError,
  KyshiValidationError,
} from '@kyshi/mor-sdk';

try {
  await kyshi.transactions.verify('ORDER-10001');
} catch (error) {
  if (error instanceof KyshiValidationError) {
    // Handle bad request or validation errors.
  } else if (error instanceof KyshiAuthenticationError) {
    // Check the secret key or account access.
  } else if (error instanceof KyshiTimeoutError) {
    // Retry later or show a temporary failure.
  } else if (error instanceof KyshiNetworkError) {
    // Inspect network connectivity.
  } else if (error instanceof KyshiApiError) {
    console.error(error.statusCode, error.code, error.message);
  } else {
    throw error;
  }
}

Webhook Methods

Method	Description
`generateSignature(payload, secret)`	Generate a Kyshi-compatible HMAC signature.
`verifySignature(payload, signature, secret)`	Return `true` when the signature is valid.
`constructEvent(payload, signature, secret)`	Verify and return the trusted payload.
`listEvents(query)`	List webhook event records.
`retrieveEvent(eventId)`	Retrieve one webhook event record.
`replayEvent(eventId)`	Replay a webhook event.
`listFailed(query)`	List failed webhook transactions.
`retryTransaction(transactionId)`	Retry webhook delivery for a transaction.
`bulkRetry(params)`	Retry failed webhook deliveries in bulk.
`stats(query)`	Retrieve webhook failure stats.
`reliabilityStats(query)`	Retrieve reliability stats.