Validate method 📢 Webhooks

Validates whether your enrolled webhook(s) respond with an HTTP 2xx status code. Sends a test request to each webhook containing your customer handle, a hardcoded event type (test), a hardcoded sender email (test@mailchannels.com), a timestamp, a request ID (provided or generated), and an SMTP ID. The response includes the HTTP status code and body returned by each webhook.

Usage

modular.ts

import { MailChannelsClient, Webhooks } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const webhooks = new Webhooks(mailchannels)

const { data, error } = await webhooks.validate('optional-request-id')

full.ts

import { MailChannels } from 'mailchannels-sdk'

const mailchannels = new MailChannels('your-api-key')

const { data, error } = await mailchannels.webhooks.validate('optional-request-id')

Params

• requestId string optional: Optional identifier in the webhook payload. If not provided, a value will be automatically generated.

  NOTE

  The request id must not exceed 28 characters.

Response

• data object | null nullable
  • allPassed boolean guaranteed: Indicates whether all webhook validations passed
  • results object[] guaranteed: Detailed results for each tested webhook, including whether it returned a 2xx status code, along with its response status code and body.
    • result "passed" | "failed" guaranteed: Indicates whether the webhook responded with a 2xx HTTP status code.
    • webhook string guaranteed: The webhook that was validated.
    • response object | null nullable: The HTTP response returned by the webhook, including status code and response body. A null value indicates no response was received. Possible reasons include timeouts, connection failures, or other network-related issues.
      • body string optional: Response body from webhook. Returns an error if unprocessable or too large.
      • status number guaranteed: HTTP status code returned by the webhook.
• error ErrorResponse | null nullable: Error information if the operation failed.
  • message string guaranteed: A human-readable description of the error.
  • statusCode number | null nullable: The HTTP status code from the API, or null if the error is not related to an HTTP request. This field is intended for diagnostic use only and should not be relied upon.
  • type string guaranteed: A string identifier for the type of error. This field is intended for diagnostic use only and should not be relied upon.

Type declarations

Signature

async function validate (requestId?: string): Promise<WebhooksValidateResponse>

Response type declarations

interface ErrorResponse {
  message: string;
  statusCode: number | null;
  type: ErrorType;
}

type DataResponse<T> = {
  data: T;
  error: null;
} | {
  data: null;
  error: ErrorResponse;
};

Validate type declarations

type WebhooksValidateResponse = DataResponse<{
  allPassed: boolean;
  results: {
    result: "passed" | "failed";
    webhook: string;
    response: {
      body?: string;
      status: number;
    } | null;
  }[];
}>;

Source

Source • Playground • Docs • Tests