@sendly/node 1.0.7 → 1.1.0

package/dist/index.d.ts

@@ -47,8 +47,13 @@ interface SendMessageRequest {
 }
 /**
  * Message status values
+ * Note: "sending" was removed as it doesn't exist in the database
  */
-type MessageStatus = "queued" | "sending" | "sent" | "delivered" | "failed";
+type MessageStatus = "queued" | "sent" | "delivered" | "failed";
+/**
+ * How the message was sent
+ */
+type SenderType = "number_pool" | "alphanumeric" | "sandbox";
 /**
  * A sent or received SMS message
  */
@@ -73,6 +78,10 @@ interface Message {
      * Current delivery status
      */
     status: MessageStatus;
+    /**
+     * Message direction
+     */
+    direction: "outbound" | "inbound";
     /**
      * Error message if status is "failed"
      */
@@ -89,6 +98,25 @@ interface Message {
      * Whether this message was sent in sandbox mode
      */
     isSandbox: boolean;
+    /**
+     * How the message was sent
+     * - "number_pool": Sent from toll-free number pool (US/CA)
+     * - "alphanumeric": Sent with alphanumeric sender ID (international)
+     * - "sandbox": Sent in sandbox/test mode
+     */
+    senderType?: SenderType;
+    /**
+     * Telnyx message ID for tracking
+     */
+    telnyxMessageId?: string | null;
+    /**
+     * Warning message (e.g., when "from" is ignored for domestic messages)
+     */
+    warning?: string;
+    /**
+     * Note about sender behavior (e.g., toll-free number pool explanation)
+     */
+    senderNote?: string;
     /**
      * ISO 8601 timestamp when the message was created
      */
@@ -478,6 +506,219 @@ declare const SUPPORTED_COUNTRIES: Record<PricingTier, string[]>;
  * All supported country codes
  */
 declare const ALL_SUPPORTED_COUNTRIES: string[];
+/**
+ * Webhook event types
+ */
+type WebhookEventType = "message.sent" | "message.delivered" | "message.failed" | "message.bounced" | "message.queued";
+/**
+ * Circuit breaker state for webhook delivery
+ */
+type CircuitState = "closed" | "open" | "half_open";
+/**
+ * Webhook delivery status
+ */
+type DeliveryStatus = "pending" | "delivered" | "failed" | "cancelled";
+/**
+ * A configured webhook endpoint
+ */
+interface Webhook {
+    /** Unique webhook identifier (whk_xxx) */
+    id: string;
+    /** HTTPS endpoint URL */
+    url: string;
+    /** Event types this webhook subscribes to */
+    events: WebhookEventType[];
+    /** Optional description */
+    description?: string;
+    /** Whether the webhook is active */
+    isActive: boolean;
+    /** Number of consecutive failures */
+    failureCount: number;
+    /** Last failure timestamp (ISO 8601) */
+    lastFailureAt?: string | null;
+    /** Circuit breaker state */
+    circuitState: CircuitState;
+    /** When circuit was opened (ISO 8601) */
+    circuitOpenedAt?: string | null;
+    /** API version for payloads */
+    apiVersion: string;
+    /** Custom metadata */
+    metadata: Record<string, unknown>;
+    /** When webhook was created (ISO 8601) */
+    createdAt: string;
+    /** When webhook was last updated (ISO 8601) */
+    updatedAt: string;
+    /** Total delivery attempts */
+    totalDeliveries: number;
+    /** Successful deliveries */
+    successfulDeliveries: number;
+    /** Success rate (0-100) */
+    successRate: number;
+    /** Last successful delivery (ISO 8601) */
+    lastDeliveryAt?: string | null;
+}
+/**
+ * Response when creating a webhook (includes secret once)
+ */
+interface WebhookCreatedResponse extends Webhook {
+    /** Webhook signing secret - only shown once at creation */
+    secret: string;
+}
+/**
+ * Options for creating a webhook
+ */
+interface CreateWebhookOptions {
+    /** HTTPS endpoint URL */
+    url: string;
+    /** Event types to subscribe to */
+    events: WebhookEventType[];
+    /** Optional description */
+    description?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for updating a webhook
+ */
+interface UpdateWebhookOptions {
+    /** New URL */
+    url?: string;
+    /** New event subscriptions */
+    events?: WebhookEventType[];
+    /** New description */
+    description?: string;
+    /** Enable/disable webhook */
+    isActive?: boolean;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A webhook delivery attempt
+ */
+interface WebhookDelivery {
+    /** Unique delivery identifier (del_xxx) */
+    id: string;
+    /** Webhook ID this delivery belongs to */
+    webhookId: string;
+    /** Event ID for idempotency */
+    eventId: string;
+    /** Event type */
+    eventType: WebhookEventType;
+    /** Attempt number (1-6) */
+    attemptNumber: number;
+    /** Maximum attempts allowed */
+    maxAttempts: number;
+    /** Delivery status */
+    status: DeliveryStatus;
+    /** HTTP response status code */
+    responseStatusCode?: number;
+    /** Response time in milliseconds */
+    responseTimeMs?: number;
+    /** Error message if failed */
+    errorMessage?: string;
+    /** Error code if failed */
+    errorCode?: string;
+    /** Next retry time (ISO 8601) */
+    nextRetryAt?: string;
+    /** When delivery was created (ISO 8601) */
+    createdAt: string;
+    /** When delivery succeeded (ISO 8601) */
+    deliveredAt?: string;
+}
+/**
+ * Response from testing a webhook
+ */
+interface WebhookTestResult {
+    /** Whether test was successful */
+    success: boolean;
+    /** HTTP status code from endpoint */
+    statusCode?: number;
+    /** Response time in milliseconds */
+    responseTimeMs?: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Response from rotating webhook secret
+ */
+interface WebhookSecretRotation {
+    /** The webhook */
+    webhook: Webhook;
+    /** New signing secret */
+    newSecret: string;
+    /** When old secret expires (ISO 8601) */
+    oldSecretExpiresAt: string;
+    /** Message about grace period */
+    message: string;
+}
+/**
+ * Account information
+ */
+interface Account {
+    /** User ID */
+    id: string;
+    /** Email address */
+    email: string;
+    /** Display name */
+    name?: string;
+    /** Account creation date (ISO 8601) */
+    createdAt: string;
+}
+/**
+ * Credit balance information
+ */
+interface Credits {
+    /** Available credit balance */
+    balance: number;
+    /** Credits reserved for scheduled messages */
+    reservedBalance: number;
+    /** Total usable credits (balance - reserved) */
+    availableBalance: number;
+}
+/**
+ * A credit transaction record
+ */
+interface CreditTransaction {
+    /** Transaction ID */
+    id: string;
+    /** Transaction type */
+    type: "purchase" | "usage" | "refund" | "adjustment" | "bonus";
+    /** Amount (positive for credits in, negative for credits out) */
+    amount: number;
+    /** Balance after transaction */
+    balanceAfter: number;
+    /** Transaction description */
+    description: string;
+    /** Related message ID (for usage transactions) */
+    messageId?: string;
+    /** When transaction occurred (ISO 8601) */
+    createdAt: string;
+}
+/**
+ * An API key
+ */
+interface ApiKey {
+    /** Key ID */
+    id: string;
+    /** Key name/label */
+    name: string;
+    /** Key type */
+    type: "test" | "live";
+    /** Key prefix (for identification) */
+    prefix: string;
+    /** Last 4 characters of key */
+    lastFour: string;
+    /** Permissions granted */
+    permissions: string[];
+    /** When key was created (ISO 8601) */
+    createdAt: string;
+    /** When key was last used (ISO 8601) */
+    lastUsedAt?: string | null;
+    /** When key expires (ISO 8601) */
+    expiresAt?: string | null;
+    /** Whether key is revoked */
+    isRevoked: boolean;
+}
 /**
  * Test phone numbers for sandbox mode
  */
@@ -805,6 +1046,331 @@ declare class MessagesResource {
     listBatches(options?: ListBatchesOptions): Promise<BatchListResponse>;
 }
 
+/**
+ * Webhooks Resource
+ * @packageDocumentation
+ */
+
+/**
+ * Webhooks API resource
+ *
+ * Manage webhook endpoints for receiving real-time message status updates.
+ *
+ * @example
+ * ```typescript
+ * // Create a webhook
+ * const webhook = await sendly.webhooks.create({
+ *   url: 'https://example.com/webhooks/sendly',
+ *   events: ['message.delivered', 'message.failed']
+ * });
+ *
+ * // IMPORTANT: Save the secret - it's only shown once!
+ * console.log('Secret:', webhook.secret);
+ *
+ * // List webhooks
+ * const webhooks = await sendly.webhooks.list();
+ *
+ * // Test a webhook
+ * const result = await sendly.webhooks.test(webhook.id);
+ * ```
+ */
+declare class WebhooksResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new webhook endpoint
+     *
+     * @param options - Webhook configuration
+     * @returns The created webhook with signing secret (shown only once!)
+     *
+     * @example
+     * ```typescript
+     * const webhook = await sendly.webhooks.create({
+     *   url: 'https://example.com/webhooks/sendly',
+     *   events: ['message.delivered', 'message.failed'],
+     *   description: 'Production webhook'
+     * });
+     *
+     * // IMPORTANT: Save this secret securely - it's only shown once!
+     * console.log('Webhook secret:', webhook.secret);
+     * ```
+     *
+     * @throws {ValidationError} If the URL is invalid or events are empty
+     * @throws {AuthenticationError} If the API key is invalid
+     */
+    create(options: CreateWebhookOptions): Promise<WebhookCreatedResponse>;
+    /**
+     * List all webhooks
+     *
+     * @returns Array of webhook configurations
+     *
+     * @example
+     * ```typescript
+     * const webhooks = await sendly.webhooks.list();
+     *
+     * for (const webhook of webhooks) {
+     *   console.log(`${webhook.id}: ${webhook.url} (${webhook.isActive ? 'active' : 'inactive'})`);
+     * }
+     * ```
+     */
+    list(): Promise<Webhook[]>;
+    /**
+     * Get a specific webhook by ID
+     *
+     * @param id - Webhook ID (whk_xxx)
+     * @returns The webhook details
+     *
+     * @example
+     * ```typescript
+     * const webhook = await sendly.webhooks.get('whk_xxx');
+     * console.log(`Success rate: ${webhook.successRate}%`);
+     * ```
+     *
+     * @throws {NotFoundError} If the webhook doesn't exist
+     */
+    get(id: string): Promise<Webhook>;
+    /**
+     * Update a webhook configuration
+     *
+     * @param id - Webhook ID
+     * @param options - Fields to update
+     * @returns The updated webhook
+     *
+     * @example
+     * ```typescript
+     * // Update URL
+     * await sendly.webhooks.update('whk_xxx', {
+     *   url: 'https://new-endpoint.example.com/webhooks'
+     * });
+     *
+     * // Disable webhook
+     * await sendly.webhooks.update('whk_xxx', { isActive: false });
+     *
+     * // Change event subscriptions
+     * await sendly.webhooks.update('whk_xxx', {
+     *   events: ['message.delivered']
+     * });
+     * ```
+     */
+    update(id: string, options: UpdateWebhookOptions): Promise<Webhook>;
+    /**
+     * Delete a webhook
+     *
+     * @param id - Webhook ID
+     *
+     * @example
+     * ```typescript
+     * await sendly.webhooks.delete('whk_xxx');
+     * ```
+     *
+     * @throws {NotFoundError} If the webhook doesn't exist
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Send a test event to a webhook endpoint
+     *
+     * @param id - Webhook ID
+     * @returns Test result with response details
+     *
+     * @example
+     * ```typescript
+     * const result = await sendly.webhooks.test('whk_xxx');
+     *
+     * if (result.success) {
+     *   console.log(`Test passed! Response time: ${result.responseTimeMs}ms`);
+     * } else {
+     *   console.log(`Test failed: ${result.error}`);
+     * }
+     * ```
+     */
+    test(id: string): Promise<WebhookTestResult>;
+    /**
+     * Rotate the webhook signing secret
+     *
+     * The old secret remains valid for 24 hours to allow for graceful migration.
+     *
+     * @param id - Webhook ID
+     * @returns New secret and expiration info
+     *
+     * @example
+     * ```typescript
+     * const rotation = await sendly.webhooks.rotateSecret('whk_xxx');
+     *
+     * // Update your webhook handler with the new secret
+     * console.log('New secret:', rotation.newSecret);
+     * console.log('Old secret expires:', rotation.oldSecretExpiresAt);
+     * ```
+     */
+    rotateSecret(id: string): Promise<WebhookSecretRotation>;
+    /**
+     * Get delivery history for a webhook
+     *
+     * @param id - Webhook ID
+     * @returns Array of delivery attempts
+     *
+     * @example
+     * ```typescript
+     * const deliveries = await sendly.webhooks.getDeliveries('whk_xxx');
+     *
+     * for (const delivery of deliveries) {
+     *   console.log(`${delivery.eventType}: ${delivery.status} (${delivery.responseTimeMs}ms)`);
+     * }
+     * ```
+     */
+    getDeliveries(id: string): Promise<WebhookDelivery[]>;
+    /**
+     * Retry a failed delivery
+     *
+     * @param webhookId - Webhook ID
+     * @param deliveryId - Delivery ID
+     *
+     * @example
+     * ```typescript
+     * await sendly.webhooks.retryDelivery('whk_xxx', 'del_yyy');
+     * ```
+     */
+    retryDelivery(webhookId: string, deliveryId: string): Promise<void>;
+    /**
+     * List available event types
+     *
+     * @returns Array of event type strings
+     *
+     * @example
+     * ```typescript
+     * const eventTypes = await sendly.webhooks.listEventTypes();
+     * console.log('Available events:', eventTypes);
+     * // ['message.sent', 'message.delivered', 'message.failed', 'message.bounced']
+     * ```
+     */
+    listEventTypes(): Promise<WebhookEventType[]>;
+}
+
+/**
+ * Account Resource
+ * @packageDocumentation
+ */
+
+/**
+ * Account API resource
+ *
+ * Access account information, credit balance, and API keys.
+ *
+ * @example
+ * ```typescript
+ * // Get credit balance
+ * const credits = await sendly.account.getCredits();
+ * console.log(`Available: ${credits.availableBalance} credits`);
+ *
+ * // Get transaction history
+ * const transactions = await sendly.account.getCreditTransactions();
+ *
+ * // List API keys
+ * const keys = await sendly.account.listApiKeys();
+ * ```
+ */
+declare class AccountResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get account information
+     *
+     * @returns Account details
+     *
+     * @example
+     * ```typescript
+     * const account = await sendly.account.get();
+     * console.log(`Account: ${account.email}`);
+     * ```
+     */
+    get(): Promise<Account>;
+    /**
+     * Get credit balance
+     *
+     * @returns Current credit balance and reserved credits
+     *
+     * @example
+     * ```typescript
+     * const credits = await sendly.account.getCredits();
+     *
+     * console.log(`Total balance: ${credits.balance}`);
+     * console.log(`Reserved (scheduled): ${credits.reservedBalance}`);
+     * console.log(`Available to use: ${credits.availableBalance}`);
+     * ```
+     */
+    getCredits(): Promise<Credits>;
+    /**
+     * Get credit transaction history
+     *
+     * @param options - Pagination options
+     * @returns Array of credit transactions
+     *
+     * @example
+     * ```typescript
+     * const transactions = await sendly.account.getCreditTransactions();
+     *
+     * for (const tx of transactions) {
+     *   const sign = tx.amount > 0 ? '+' : '';
+     *   console.log(`${tx.type}: ${sign}${tx.amount} credits - ${tx.description}`);
+     * }
+     * ```
+     */
+    getCreditTransactions(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<CreditTransaction[]>;
+    /**
+     * List API keys for the account
+     *
+     * Note: This returns key metadata, not the actual secret keys.
+     *
+     * @returns Array of API keys
+     *
+     * @example
+     * ```typescript
+     * const keys = await sendly.account.listApiKeys();
+     *
+     * for (const key of keys) {
+     *   console.log(`${key.name}: ${key.prefix}...${key.lastFour} (${key.type})`);
+     * }
+     * ```
+     */
+    listApiKeys(): Promise<ApiKey[]>;
+    /**
+     * Get a specific API key by ID
+     *
+     * @param id - API key ID
+     * @returns API key details
+     *
+     * @example
+     * ```typescript
+     * const key = await sendly.account.getApiKey('key_xxx');
+     * console.log(`Last used: ${key.lastUsedAt}`);
+     * ```
+     */
+    getApiKey(id: string): Promise<ApiKey>;
+    /**
+     * Get usage statistics for an API key
+     *
+     * @param id - API key ID
+     * @returns Usage statistics
+     *
+     * @example
+     * ```typescript
+     * const usage = await sendly.account.getApiKeyUsage('key_xxx');
+     * console.log(`Messages sent: ${usage.messagesSent}`);
+     * ```
+     */
+    getApiKeyUsage(id: string): Promise<{
+        keyId: string;
+        messagesSent: number;
+        messagesDelivered: number;
+        messagesFailed: number;
+        creditsUsed: number;
+        periodStart: string;
+        periodEnd: string;
+    }>;
+}
+
 /**
  * Sendly Client
  * @packageDocumentation
@@ -858,6 +1424,41 @@ declare class Sendly {
      * ```
      */
     readonly messages: MessagesResource;
+    /**
+     * Webhooks API resource
+     *
+     * @example
+     * ```typescript
+     * // Create a webhook
+     * const webhook = await sendly.webhooks.create({
+     *   url: 'https://example.com/webhooks',
+     *   events: ['message.delivered', 'message.failed']
+     * });
+     *
+     * // List webhooks
+     * const webhooks = await sendly.webhooks.list();
+     *
+     * // Test a webhook
+     * await sendly.webhooks.test('whk_xxx');
+     * ```
+     */
+    readonly webhooks: WebhooksResource;
+    /**
+     * Account API resource
+     *
+     * @example
+     * ```typescript
+     * // Get credit balance
+     * const credits = await sendly.account.getCredits();
+     *
+     * // Get transaction history
+     * const transactions = await sendly.account.getCreditTransactions();
+     *
+     * // List API keys
+     * const keys = await sendly.account.listApiKeys();
+     * ```
+     */
+    readonly account: AccountResource;
     private readonly http;
     private readonly config;
     /**
@@ -1020,53 +1621,86 @@ declare function calculateSegments(text: string): number;
  * Provides signature verification and event parsing
  * @packageDocumentation
  */
-/**
- * Webhook event types
- */
-type WebhookEventType = "message.queued" | "message.sent" | "message.delivered" | "message.failed" | "message.undelivered";
+
 /**
  * Message status in webhook events
  */
-type WebhookMessageStatus = "queued" | "sent" | "delivered" | "failed" | "undelivered";
+type WebhookMessageStatus = "queued" | "sent" | "delivered" | "failed";
 /**
- * Webhook message data payload
+ * Message object within webhook payload
+ * Matches the structure sent by Sendly servers
  */
-interface WebhookMessageData {
-    /** Unique message identifier */
-    messageId: string;
-    /** Current message status */
-    status: WebhookMessageStatus;
-    /** Destination phone number */
+interface WebhookMessageObject {
+    /** Message ID (msg_xxx) */
+    id: string;
+    /** Recipient phone number (E.164 format) */
     to: string;
-    /** Sender ID or phone number */
+    /** Sender phone number or ID */
     from: string;
-    /** Error message if failed */
-    error?: string;
-    /** Error code if failed */
-    errorCode?: string;
-    /** ISO 8601 timestamp when delivered */
-    deliveredAt?: string;
-    /** ISO 8601 timestamp when failed */
-    failedAt?: string;
+    /** Message text content */
+    text: string;
+    /** Current message status */
+    status: WebhookMessageStatus;
+    /** Message direction */
+    direction: "outbound" | "inbound";
     /** Number of SMS segments */
     segments: number;
-    /** Credits charged */
-    creditsUsed: number;
+    /** Credits charged for this message */
+    credits_used: number;
+    /** Unix timestamp when message was created */
+    created_at: number;
+    /** Unix timestamp when message was delivered (if applicable) */
+    delivered_at?: number;
+    /** Error message if status is 'failed' */
+    error?: string;
+    /** Custom metadata attached to the message */
+    metadata?: Record<string, unknown>;
 }
 /**
- * Webhook event structure
+ * Webhook event payload from Sendly
+ * This is the exact structure sent to your webhook endpoints
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "evt_abc123",
+ *   "type": "message.delivered",
+ *   "api_version": "2024-01",
+ *   "created": 1702000000,
+ *   "livemode": true,
+ *   "data": {
+ *     "object": {
+ *       "id": "msg_xyz789",
+ *       "to": "+15551234567",
+ *       "from": "+15559876543",
+ *       "text": "Hello!",
+ *       "status": "delivered",
+ *       "direction": "outbound",
+ *       "segments": 1,
+ *       "credits_used": 1,
+ *       "created_at": 1702000000,
+ *       "delivered_at": 1702000005
+ *     }
+ *   }
+ * }
+ * ```
  */
 interface WebhookEvent {
-    /** Unique event identifier */
+    /** Unique event identifier (evt_xxx) for idempotency */
     id: string;
     /** Event type */
     type: WebhookEventType;
-    /** Event data payload */
-    data: WebhookMessageData;
-    /** ISO 8601 timestamp when event was created */
-    createdAt: string;
     /** API version that generated this event */
-    apiVersion: string;
+    api_version: string;
+    /** Unix timestamp (seconds) when event was created */
+    created: number;
+    /** Whether this event is from live mode (true) or sandbox (false) */
+    livemode: boolean;
+    /** Event data containing the message object */
+    data: {
+        /** The message object that triggered this event */
+        object: WebhookMessageObject;
+    };
 }
 /**
  * Error thrown when webhook signature verification fails
@@ -1077,33 +1711,50 @@ declare class WebhookSignatureError extends Error {
 /**
  * Verify a webhook signature from Sendly
  *
- * @param payload - Raw request body as string
+ * Sendly signs webhooks using HMAC-SHA256. The signature format is:
+ * `sha256=<hex_digest>`
+ *
+ * The signed payload is: `<timestamp>.<json_body>`
+ *
+ * @param payload - Raw request body as string (JSON)
  * @param signature - X-Sendly-Signature header value
  * @param secret - Your webhook secret from dashboard
+ * @param timestamp - X-Sendly-Timestamp header value (optional, for enhanced verification)
+ * @param toleranceSeconds - Maximum age of webhook in seconds (default: 300 = 5 minutes)
  * @returns true if signature is valid
  *
  * @example
  * ```typescript
  * import { verifyWebhookSignature } from '@sendly/node';
  *
+ * // Basic verification
  * const isValid = verifyWebhookSignature(
  *   req.body, // raw body string
  *   req.headers['x-sendly-signature'],
  *   process.env.WEBHOOK_SECRET
  * );
  *
+ * // With timestamp verification (recommended)
+ * const isValid = verifyWebhookSignature(
+ *   req.body,
+ *   req.headers['x-sendly-signature'],
+ *   process.env.WEBHOOK_SECRET,
+ *   req.headers['x-sendly-timestamp']
+ * );
+ *
  * if (!isValid) {
  *   return res.status(401).send('Invalid signature');
  * }
  * ```
  */
-declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string, timestamp?: string, toleranceSeconds?: number): boolean;
 /**
  * Parse and verify a webhook event
  *
  * @param payload - Raw request body as string
  * @param signature - X-Sendly-Signature header value
  * @param secret - Your webhook secret from dashboard
+ * @param timestamp - X-Sendly-Timestamp header value (optional)
  * @returns Parsed webhook event
  * @throws {WebhookSignatureError} If signature is invalid
  *
@@ -1115,15 +1766,16 @@ declare function verifyWebhookSignature(payload: string, signature: string, secr
  *   const event = parseWebhookEvent(
  *     req.body,
  *     req.headers['x-sendly-signature'],
- *     process.env.WEBHOOK_SECRET
+ *     process.env.WEBHOOK_SECRET,
+ *     req.headers['x-sendly-timestamp']
  *   );
  *
  *   switch (event.type) {
  *     case 'message.delivered':
- *       console.log(`Message ${event.data.messageId} delivered!`);
+ *       console.log(`Message ${event.data.object.id} delivered!`);
  *       break;
  *     case 'message.failed':
- *       console.log(`Message failed: ${event.data.error}`);
+ *       console.log(`Message failed: ${event.data.object.error}`);
  *       break;
  *   }
  * } catch (err) {
@@ -1134,7 +1786,7 @@ declare function verifyWebhookSignature(payload: string, signature: string, secr
  * }
  * ```
  */
-declare function parseWebhookEvent(payload: string, signature: string, secret: string): WebhookEvent;
+declare function parseWebhookEvent(payload: string, signature: string, secret: string, timestamp?: string): WebhookEvent;
 /**
  * Generate a webhook signature for testing purposes
  *
@@ -1147,15 +1799,31 @@ declare function parseWebhookEvent(payload: string, signature: string, secret: s
  * import { generateWebhookSignature } from '@sendly/node';
  *
  * // For testing your webhook handler
+ * const timestamp = Math.floor(Date.now() / 1000);
  * const testPayload = JSON.stringify({
  *   id: 'evt_test',
  *   type: 'message.delivered',
- *   data: { messageId: 'msg_123', status: 'delivered' },
- *   createdAt: new Date().toISOString(),
- *   apiVersion: '2025-01-01'
+ *   api_version: '2024-01',
+ *   created: timestamp,
+ *   livemode: false,
+ *   data: {
+ *     object: {
+ *       id: 'msg_123',
+ *       to: '+15551234567',
+ *       from: '+15559876543',
+ *       text: 'Test message',
+ *       status: 'delivered',
+ *       direction: 'outbound',
+ *       segments: 1,
+ *       credits_used: 1,
+ *       created_at: timestamp,
+ *       delivered_at: timestamp
+ *     }
+ *   }
  * });
  *
- * const signature = generateWebhookSignature(testPayload, 'test_secret');
+ * const signedPayload = `${timestamp}.${testPayload}`;
+ * const signature = generateWebhookSignature(signedPayload, 'test_secret');
  * ```
  */
 declare function generateWebhookSignature(payload: string, secret: string): string;
@@ -1168,11 +1836,25 @@ declare function generateWebhookSignature(payload: string, secret: string): stri
  *
  * const webhooks = new Webhooks('your_webhook_secret');
  *
- * // Verify signature
- * const isValid = webhooks.verify(payload, signature);
+ * // In your Express/Fastify/etc handler:
+ * app.post('/webhooks/sendly', (req, res) => {
+ *   try {
+ *     const event = webhooks.parse(
+ *       req.body,
+ *       req.headers['x-sendly-signature'],
+ *       req.headers['x-sendly-timestamp']
+ *     );
+ *
+ *     // Handle the event
+ *     if (event.type === 'message.delivered') {
+ *       console.log(`Message ${event.data.object.id} delivered!`);
+ *     }
  *
- * // Parse event
- * const event = webhooks.parse(payload, signature);
+ *     res.status(200).send('OK');
+ *   } catch (err) {
+ *     res.status(401).send('Invalid signature');
+ *   }
+ * });
  * ```
  */
 declare class Webhooks {
@@ -1186,19 +1868,45 @@ declare class Webhooks {
      * Verify a webhook signature
      * @param payload - Raw request body
      * @param signature - X-Sendly-Signature header
+     * @param timestamp - X-Sendly-Timestamp header (optional)
      */
-    verify(payload: string, signature: string): boolean;
+    verify(payload: string, signature: string, timestamp?: string): boolean;
     /**
      * Parse and verify a webhook event
      * @param payload - Raw request body
      * @param signature - X-Sendly-Signature header
+     * @param timestamp - X-Sendly-Timestamp header (optional)
      */
-    parse(payload: string, signature: string): WebhookEvent;
+    parse(payload: string, signature: string, timestamp?: string): WebhookEvent;
     /**
      * Generate a signature for testing
-     * @param payload - Payload to sign
+     * @param payload - Payload to sign (should include timestamp prefix if using timestamps)
      */
     sign(payload: string): string;
+    /**
+     * Verify a webhook signature (static method for backwards compatibility)
+     * @param payload - Raw request body
+     * @param signature - X-Sendly-Signature header
+     * @param secret - Your webhook secret
+     */
+    static verifySignature(payload: string, signature: string, secret: string): boolean;
+    /**
+     * Parse and verify a webhook event (static method for backwards compatibility)
+     * @param payload - Raw request body
+     * @param signature - X-Sendly-Signature header
+     * @param secret - Your webhook secret
+     */
+    static parseEvent(payload: string, signature: string, secret: string): WebhookEvent;
+    /**
+     * Generate a webhook signature (static method for backwards compatibility)
+     * @param payload - Payload to sign
+     * @param secret - Secret to use for signing
+     */
+    static generateSignature(payload: string, secret: string): string;
 }
+/**
+ * @deprecated Use WebhookMessageObject instead
+ */
+type WebhookMessageData = WebhookMessageObject;
 
-export { ALL_SUPPORTED_COUNTRIES, type ApiErrorResponse, AuthenticationError, CREDITS_PER_SMS, InsufficientCreditsError, type ListMessagesOptions, type Message, type MessageListResponse, type MessageStatus, NetworkError, NotFoundError, type PricingTier, RateLimitError, type RateLimitInfo, SANDBOX_TEST_NUMBERS, SUPPORTED_COUNTRIES, type SendMessageRequest, Sendly, type SendlyConfig, SendlyError, type SendlyErrorCode, TimeoutError, ValidationError, type WebhookEvent, type WebhookEventType, type WebhookMessageData, type WebhookMessageStatus, WebhookSignatureError, Webhooks, calculateSegments, Sendly as default, generateWebhookSignature, getCountryFromPhone, isCountrySupported, parseWebhookEvent, validateMessageText, validatePhoneNumber, validateSenderId, verifyWebhookSignature };
+export { ALL_SUPPORTED_COUNTRIES, type Account, type ApiErrorResponse, type ApiKey, AuthenticationError, type BatchListResponse, type BatchMessageItem, type BatchMessageRequest, type BatchMessageResponse, type BatchMessageResult, type BatchStatus, CREDITS_PER_SMS, type CancelledMessageResponse, type CircuitState, type CreateWebhookOptions, type CreditTransaction, type Credits, type DeliveryStatus, InsufficientCreditsError, type ListBatchesOptions, type ListMessagesOptions, type ListScheduledMessagesOptions, type Message, type MessageListResponse, type MessageStatus, NetworkError, NotFoundError, type PricingTier, RateLimitError, type RateLimitInfo, SANDBOX_TEST_NUMBERS, SUPPORTED_COUNTRIES, type ScheduleMessageRequest, type ScheduledMessage, type ScheduledMessageListResponse, type ScheduledMessageStatus, type SendMessageRequest, type SenderType, Sendly, type SendlyConfig, SendlyError, type SendlyErrorCode, TimeoutError, type UpdateWebhookOptions, ValidationError, type Webhook, type WebhookCreatedResponse, type WebhookDelivery, type WebhookEvent, type WebhookEventType, type WebhookMessageData, type WebhookMessageStatus, type WebhookSecretRotation, WebhookSignatureError, type WebhookTestResult, Webhooks, calculateSegments, Sendly as default, generateWebhookSignature, getCountryFromPhone, isCountrySupported, parseWebhookEvent, validateMessageText, validatePhoneNumber, validateSenderId, verifyWebhookSignature };