📢 Webhooks module Email API

Receive notifications of your email events via webhooks.

Methods

• Create Webhook
• List Webhooks
• Delete All Webhooks
• Get Signing Key
• Validate Webhooks
• Verify a message
• Retrieve Webhook Batches
• Resend Batch

Type declarations

class Webhooks {
  constructor (protected mailchannels: MailChannelsClient);
  async create (endpoint: string): Promise<SuccessResponse>;
  async list (): Promise<WebhooksListResponse>;
  async deleteAll (): Promise<SuccessResponse>;
  async getSigningKey (id: string): Promise<WebhooksSigningKeyResponse>;
  async validate (requestId?: string): Promise<WebhooksValidateResponse>;
  static async verify (options: WebhooksVerifyOptions): Promise<WebhooksVerifyResponse>;
  async verify (options: WebhooksVerifyOptions): Promise<WebhooksVerifyResponse>;
  async batches (options?: WebhooksBatchesOptions): Promise<WebhooksBatchesResponse>;
  async resendBatch (batchId: number): Promise<WebhooksResendBatchResponse>;
}

All type declarations

Response type declarations

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

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

interface SuccessResponse {
  success: boolean;
  error: ErrorResponse | null;
}

List type declarations

type WebhooksListResponse = DataResponse<{
  webhook: string;
}[]>;

Signing Key type declarations

type WebhooksSigningKeyResponse = DataResponse<{
  id: string;
  key: string;
}>;

Validate type declarations

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

Verify type declarations

interface WebhooksVerifyOptions {
  payload: string;
  headers: Record<string, string> | {
    "content-digest": string;
    "signature": string;
    "signature-input": string;
  };
  publicKey?: string;
  cache?: boolean;
}

Batches type declarations

type WebhooksBatchStatus = "1xx" | "2xx" | "3xx" | "4xx" | "5xx" | "no_response";

interface WebhooksBatchesOptions {
  createdAfter?: string;
  createdBefore?: string;
  statuses?: WebhooksBatchStatus[];
  webhook?: string;
  limit?: number;
  offset?: number;
}

type WebhooksBatchResponseStatus = "1xx_response" | "2xx_response" | "3xx_response" | "4xx_response" | "5xx_response" | "no_response";

interface WebhooksBatch {
  batchId: number;
  createdAt: string;
  customerHandle: string;
  duration?: {
    unit: "milliseconds";
    value: number;
  };
  eventCount: number;
  status: WebhooksBatchResponseStatus;
  statusCode: number | null;
  webhook: string;
}

type WebhooksBatchesResponse = DataResponse<WebhooksBatch[]>;

Resend Batch type declarations

interface WebhooksResendBatch {
  batchId: number;
  customerHandle: string;
  webhook: string;
  createdAt: string;
  eventCount: number;
  duration: number | null;
  statusCode: number | null;
}

type WebhooksResendBatchResponse = DataResponse<WebhooksResendBatch>;

Source

Source • Playground • Docs • Tests

Changelog

• Unreleased on May 26, 2026

  • f49c49f — feat(errors): introduce error type keys

• v0.8.0 on May 23, 2026

  • ab66dc1 — refactor: split internal utils into focused modules
  • bd4c25f — refactor!: rename webhooks enroll and dkim update methods
  • df90058 — refactor(webhooks)!: return full event object in verify
  • d9d5ba6 — refactor!: return structured response from webhooks.verify
  • 0be7bd6 — refactor!: rename webhooks.delete to webhooks.deleteAll