@linqapp/sdk 0.25.0 → 0.27.0

package/src/resources/webhook-events.ts

@@ -17,55 +17,82 @@ import { RequestOptions } from '../internal/request-options';
  *
  * ## Webhook Headers
  *
- * Each webhook request includes the following headers:
+ * All webhook requests include two sets of headers. **If you have an existing integration
+ * using the `X-Webhook-*` headers, nothing changes** — those headers are still sent on
+ * every delivery and work exactly as before. The new `webhook-*` headers follow the
+ * [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks) specification.
+ * You can safely ignore them if your current verification code works and you don't want to use this convention.
+ *
+ * ### Standard Webhooks Headers (Recommended)
+ *
+ * Used by [our SDK](https://github.com/linq-team/linq-node) and any [Standard Webhooks library](https://github.com/standard-webhooks/standard-webhooks).
  *
  * | Header | Description |
  * |--------|-------------|
- * | `X-Webhook-Event` | The event type (e.g., `message.sent`, `message.received`) |
- * | `X-Webhook-Subscription-ID` | Your webhook subscription ID |
- * | `X-Webhook-Timestamp` | Unix timestamp (seconds) when the webhook was sent |
- * | `X-Webhook-Signature` | HMAC-SHA256 signature for verification |
+ * | `webhook-id` | Unique event identifier (use as idempotency key) |
+ * | `webhook-timestamp` | Unix timestamp (seconds) when the webhook was sent |
+ * | `webhook-signature` | Standard Webhooks signature (`v1,{base64}` format) |
  *
- * ## Verifying Webhook Signatures
+ * ### Legacy Headers (Deprecated)
+ *
+ * Still sent on every delivery for backwards compatibility. Existing verification code
+ * using these headers continues to work — no changes required.
  *
- * All webhooks are signed using HMAC-SHA256. You should always verify the signature
- * to ensure the webhook originated from Linq and hasn't been tampered with.
+ * | Header | Description |
+ * |--------|-------------|
+ * | `X-Webhook-Event` | *(deprecated)* Event type (e.g., `message.sent`) |
+ * | `X-Webhook-Subscription-ID` | *(deprecated)* Webhook subscription ID |
+ * | `X-Webhook-Timestamp` | *(deprecated)* Unix timestamp (seconds) |
+ * | `X-Webhook-Signature` | *(deprecated)* HMAC-SHA256 signature (hex-encoded) |
  *
- * **Signature Construction:**
+ * ## Signing Secrets
  *
- * The signature is computed over a concatenation of the timestamp and payload:
+ * Signing secrets use the Standard Webhooks format: a `whsec_` prefix followed
+ * by base64-encoded random bytes (e.g., `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw7Jxx2Oll+OE=`).
  *
- * ```
- * {timestamp}.{payload}
- * ```
+ * Strip the `whsec_` prefix and base64-decode the remainder to get the raw key bytes.
  *
- * Where:
- * - `timestamp` is the value from the `X-Webhook-Timestamp` header
- * - `payload` is the raw JSON request body (exact bytes, not re-serialized)
+ * ## Verifying Webhook Signatures
+ *
+ * Webhooks are signed following the [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks).
+ * You can use any [Standard Webhooks library](https://github.com/standard-webhooks/standard-webhooks) to verify
+ * signatures, or implement verification manually:
+ *
+ * **Signed content:** `{webhook-id}.{webhook-timestamp}.{body}`
  *
  * **Verification Steps:**
  *
- * 1. Extract the `X-Webhook-Timestamp` and `X-Webhook-Signature` headers
- * 2. Get the raw request body bytes (do not parse and re-serialize)
- * 3. Concatenate: `"{timestamp}.{payload}"`
- * 4. Compute HMAC-SHA256 using your signing secret as the key
- * 5. Hex-encode the result and compare with `X-Webhook-Signature`
- * 6. Use constant-time comparison to prevent timing attacks
+ * 1. Extract the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers
+ * 2. Reject if the timestamp is more than 5 minutes old (replay protection)
+ * 3. Get the raw request body bytes (do not parse and re-serialize)
+ * 4. Construct signed content: `"{webhook-id}.{webhook-timestamp}.{body}"`
+ * 5. Strip the `whsec_` prefix from your secret and base64-decode to get key bytes
+ * 6. Compute HMAC-SHA256 using the key bytes over the signed content
+ * 7. Base64-encode the result and compare with the value after `v1,` in `webhook-signature`
+ * 8. Use constant-time comparison to prevent timing attacks
  *
  * **Example (Python):**
  *
  * ```python
- * import hmac
- * import hashlib
- *
- * def verify_webhook(signing_secret, payload, timestamp, signature):
- *     message = f"{timestamp}.{payload.decode('utf-8')}"
- *     expected = hmac.new(
- *         signing_secret.encode('utf-8'),
- *         message.encode('utf-8'),
- *         hashlib.sha256
- *     ).hexdigest()
- *     return hmac.compare_digest(expected, signature)
+ * import base64, hmac, hashlib
+ *
+ * def verify_webhook(secret, body, headers):
+ *     msg_id = headers['webhook-id']
+ *     timestamp = headers['webhook-timestamp']
+ *     signature = headers['webhook-signature']
+ *
+ *     secret_str = secret.removeprefix('whsec_')
+ *     key = base64.b64decode(secret_str)
+ *
+ *     signed_content = f"{msg_id}.{timestamp}.{body}"
+ *     expected = base64.b64encode(
+ *         hmac.new(key, signed_content.encode(), hashlib.sha256).digest()
+ *     ).decode()
+ *
+ *     for sig in signature.split(' '):
+ *         if sig.startswith('v1,') and hmac.compare_digest(expected, sig[3:]):
+ *             return True
+ *     return False
  * ```
  *
  * **Example (Node.js):**
@@ -73,16 +100,28 @@ import { RequestOptions } from '../internal/request-options';
  * ```javascript
  * const crypto = require('crypto');
  *
- * function verifyWebhook(signingSecret, payload, timestamp, signature) {
- *   const message = `${timestamp}.${payload}`;
+ * function verifyWebhook(secret, rawBody, headers) {
+ *   const msgId = headers['webhook-id'];
+ *   const timestamp = headers['webhook-timestamp'];
+ *   const signature = headers['webhook-signature'];
+ *
+ *   const secretStr = secret.startsWith('whsec_') ? secret.slice(6) : secret;
+ *   const keyBytes = Buffer.from(secretStr, 'base64');
+ *   const signedContent = `${msgId}.${timestamp}.${rawBody}`;
  *   const expected = crypto
- *     .createHmac('sha256', signingSecret)
- *     .update(message)
- *     .digest('hex');
- *   return crypto.timingSafeEqual(
- *     Buffer.from(expected),
- *     Buffer.from(signature)
- *   );
+ *     .createHmac('sha256', keyBytes)
+ *     .update(signedContent)
+ *     .digest('base64');
+ *
+ *   return signature.split(' ').some(sig => {
+ *     if (!sig.startsWith('v1,')) return false;
+ *     try {
+ *       return crypto.timingSafeEqual(
+ *         Buffer.from(expected, 'base64'),
+ *         Buffer.from(sig.slice(3), 'base64')
+ *       );
+ *     } catch { return false; }
+ *   });
  * }
  * ```
  *
@@ -136,13 +175,15 @@ export type WebhookEventType =
   | 'call.ended'
   | 'call.failed'
   | 'call.declined'
-  | 'call.no_answer';
+  | 'call.no_answer'
+  | 'location.sharing.started'
+  | 'location.sharing.stopped';
 
 export interface WebhookEventListResponse {
   /**
    * URL to the webhook events documentation
    */
-  doc_url: 'https://apidocs.linqapp.com/documentation/webhook-events';
+  doc_url: 'https://docs.linqapp.com/guides/webhooks/events';
 
   /**
    * List of all available webhook event types

package/src/resources/webhook-subscriptions.ts

@@ -20,55 +20,82 @@ import { path } from '../internal/utils/path';
  *
  * ## Webhook Headers
  *
- * Each webhook request includes the following headers:
+ * All webhook requests include two sets of headers. **If you have an existing integration
+ * using the `X-Webhook-*` headers, nothing changes** — those headers are still sent on
+ * every delivery and work exactly as before. The new `webhook-*` headers follow the
+ * [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks) specification.
+ * You can safely ignore them if your current verification code works and you don't want to use this convention.
+ *
+ * ### Standard Webhooks Headers (Recommended)
+ *
+ * Used by [our SDK](https://github.com/linq-team/linq-node) and any [Standard Webhooks library](https://github.com/standard-webhooks/standard-webhooks).
  *
  * | Header | Description |
  * |--------|-------------|
- * | `X-Webhook-Event` | The event type (e.g., `message.sent`, `message.received`) |
- * | `X-Webhook-Subscription-ID` | Your webhook subscription ID |
- * | `X-Webhook-Timestamp` | Unix timestamp (seconds) when the webhook was sent |
- * | `X-Webhook-Signature` | HMAC-SHA256 signature for verification |
+ * | `webhook-id` | Unique event identifier (use as idempotency key) |
+ * | `webhook-timestamp` | Unix timestamp (seconds) when the webhook was sent |
+ * | `webhook-signature` | Standard Webhooks signature (`v1,{base64}` format) |
  *
- * ## Verifying Webhook Signatures
+ * ### Legacy Headers (Deprecated)
+ *
+ * Still sent on every delivery for backwards compatibility. Existing verification code
+ * using these headers continues to work — no changes required.
  *
- * All webhooks are signed using HMAC-SHA256. You should always verify the signature
- * to ensure the webhook originated from Linq and hasn't been tampered with.
+ * | Header | Description |
+ * |--------|-------------|
+ * | `X-Webhook-Event` | *(deprecated)* Event type (e.g., `message.sent`) |
+ * | `X-Webhook-Subscription-ID` | *(deprecated)* Webhook subscription ID |
+ * | `X-Webhook-Timestamp` | *(deprecated)* Unix timestamp (seconds) |
+ * | `X-Webhook-Signature` | *(deprecated)* HMAC-SHA256 signature (hex-encoded) |
  *
- * **Signature Construction:**
+ * ## Signing Secrets
  *
- * The signature is computed over a concatenation of the timestamp and payload:
+ * Signing secrets use the Standard Webhooks format: a `whsec_` prefix followed
+ * by base64-encoded random bytes (e.g., `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw7Jxx2Oll+OE=`).
  *
- * ```
- * {timestamp}.{payload}
- * ```
+ * Strip the `whsec_` prefix and base64-decode the remainder to get the raw key bytes.
  *
- * Where:
- * - `timestamp` is the value from the `X-Webhook-Timestamp` header
- * - `payload` is the raw JSON request body (exact bytes, not re-serialized)
+ * ## Verifying Webhook Signatures
+ *
+ * Webhooks are signed following the [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks).
+ * You can use any [Standard Webhooks library](https://github.com/standard-webhooks/standard-webhooks) to verify
+ * signatures, or implement verification manually:
+ *
+ * **Signed content:** `{webhook-id}.{webhook-timestamp}.{body}`
  *
  * **Verification Steps:**
  *
- * 1. Extract the `X-Webhook-Timestamp` and `X-Webhook-Signature` headers
- * 2. Get the raw request body bytes (do not parse and re-serialize)
- * 3. Concatenate: `"{timestamp}.{payload}"`
- * 4. Compute HMAC-SHA256 using your signing secret as the key
- * 5. Hex-encode the result and compare with `X-Webhook-Signature`
- * 6. Use constant-time comparison to prevent timing attacks
+ * 1. Extract the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers
+ * 2. Reject if the timestamp is more than 5 minutes old (replay protection)
+ * 3. Get the raw request body bytes (do not parse and re-serialize)
+ * 4. Construct signed content: `"{webhook-id}.{webhook-timestamp}.{body}"`
+ * 5. Strip the `whsec_` prefix from your secret and base64-decode to get key bytes
+ * 6. Compute HMAC-SHA256 using the key bytes over the signed content
+ * 7. Base64-encode the result and compare with the value after `v1,` in `webhook-signature`
+ * 8. Use constant-time comparison to prevent timing attacks
  *
  * **Example (Python):**
  *
  * ```python
- * import hmac
- * import hashlib
+ * import base64, hmac, hashlib
+ *
+ * def verify_webhook(secret, body, headers):
+ *     msg_id = headers['webhook-id']
+ *     timestamp = headers['webhook-timestamp']
+ *     signature = headers['webhook-signature']
  *
- * def verify_webhook(signing_secret, payload, timestamp, signature):
- *     message = f"{timestamp}.{payload.decode('utf-8')}"
- *     expected = hmac.new(
- *         signing_secret.encode('utf-8'),
- *         message.encode('utf-8'),
- *         hashlib.sha256
- *     ).hexdigest()
- *     return hmac.compare_digest(expected, signature)
+ *     secret_str = secret.removeprefix('whsec_')
+ *     key = base64.b64decode(secret_str)
+ *
+ *     signed_content = f"{msg_id}.{timestamp}.{body}"
+ *     expected = base64.b64encode(
+ *         hmac.new(key, signed_content.encode(), hashlib.sha256).digest()
+ *     ).decode()
+ *
+ *     for sig in signature.split(' '):
+ *         if sig.startswith('v1,') and hmac.compare_digest(expected, sig[3:]):
+ *             return True
+ *     return False
  * ```
  *
  * **Example (Node.js):**
@@ -76,16 +103,28 @@ import { path } from '../internal/utils/path';
  * ```javascript
  * const crypto = require('crypto');
  *
- * function verifyWebhook(signingSecret, payload, timestamp, signature) {
- *   const message = `${timestamp}.${payload}`;
+ * function verifyWebhook(secret, rawBody, headers) {
+ *   const msgId = headers['webhook-id'];
+ *   const timestamp = headers['webhook-timestamp'];
+ *   const signature = headers['webhook-signature'];
+ *
+ *   const secretStr = secret.startsWith('whsec_') ? secret.slice(6) : secret;
+ *   const keyBytes = Buffer.from(secretStr, 'base64');
+ *   const signedContent = `${msgId}.${timestamp}.${rawBody}`;
  *   const expected = crypto
- *     .createHmac('sha256', signingSecret)
- *     .update(message)
- *     .digest('hex');
- *   return crypto.timingSafeEqual(
- *     Buffer.from(expected),
- *     Buffer.from(signature)
- *   );
+ *     .createHmac('sha256', keyBytes)
+ *     .update(signedContent)
+ *     .digest('base64');
+ *
+ *   return signature.split(' ').some(sig => {
+ *     if (!sig.startsWith('v1,')) return false;
+ *     try {
+ *       return crypto.timingSafeEqual(
+ *         Buffer.from(expected, 'base64'),
+ *         Buffer.from(sig.slice(3), 'base64')
+ *       );
+ *     } catch { return false; }
+ *   });
  * }
  * ```
  *
@@ -115,9 +154,15 @@ export class WebhookSubscriptions extends APIResource {
    * **Webhook Delivery:**
    *
    * - Events are sent via HTTP POST to the target URL
-   * - Each request includes `X-Webhook-Signature` and `X-Webhook-Timestamp` headers
-   * - Signature is HMAC-SHA256 over `{timestamp}.{payload}` — see
-   *   [Webhook Events](/docs/webhook-events) for verification details
+   * - Each request includes
+   *   [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks)
+   *   headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`) for signature
+   *   verification
+   * - Legacy `X-Webhook-*` headers are also sent for backwards compatibility
+   *   (deprecated)
+   * - See
+   *   [Verifying Webhook Signatures](https://docs.linqapp.com/guides/webhooks#verifying-webhook-signatures)
+   *   for verification details
    * - Failed deliveries (5xx, 429, network errors) are retried up to 10 times over
    *   ~25 minutes with exponential backoff
    * - Client errors (4xx except 429) are not retried

package/src/resources/webhooks.ts

@@ -3,10 +3,20 @@
 import { APIResource } from '../core/resource';
 import * as Shared from './shared';
 import * as WebhookEventsAPI from './webhook-events';
+import { Webhook } from 'standardwebhooks';
 
 export class Webhooks extends APIResource {
-  events(body: string): EventsWebhookEvent {
-    return JSON.parse(body) as EventsWebhookEvent;
+  unwrap(
+    body: string,
+    { headers, key }: { headers: Record<string, string>; key?: string },
+  ): UnwrapWebhookEvent {
+    if (headers !== undefined) {
+      const keyStr: string | null = key === undefined ? this._client.webhookSecret : key;
+      if (keyStr === null) throw new Error('Webhook key must not be null in order to unwrap');
+      const wh = new Webhook(keyStr);
+      wh.verify(body, headers);
+    }
+    return JSON.parse(body) as UnwrapWebhookEvent;
   }
 }
 
@@ -794,7 +804,7 @@ export namespace MessageFailedWebhookEvent {
    */
   export interface Data {
     /**
-     * Error codes in webhook failure events (3007, 4001).
+     * Error codes in webhook failure events (3007, 4001, 4005).
      */
     code: number;
 
@@ -1638,7 +1648,7 @@ export namespace ChatGroupNameUpdateFailedWebhookEvent {
     chat_id: string;
 
     /**
-     * Error codes in webhook failure events (3007, 4001).
+     * Error codes in webhook failure events (3007, 4001, 4005).
      */
     error_code: number;
 
@@ -1715,7 +1725,7 @@ export namespace ChatGroupIconUpdateFailedWebhookEvent {
     chat_id: string;
 
     /**
-     * Error codes in webhook failure events (3007, 4001).
+     * Error codes in webhook failure events (3007, 4001, 4005).
      */
     error_code: number;
 
@@ -1904,7 +1914,9 @@ export interface PhoneNumberStatusUpdatedWebhookEvent {
     | 'call.ended'
     | 'call.failed'
     | 'call.declined'
-    | 'call.no_answer';
+    | 'call.no_answer'
+    | 'location.sharing.started'
+    | 'location.sharing.stopped';
 
   /**
    * Partner identifier. Present on all webhooks for cross-referencing.
@@ -1964,7 +1976,7 @@ export namespace PhoneNumberStatusUpdatedWebhookEvent {
 /**
  * Complete webhook payload for message.sent events (2026-02-03 format)
  */
-export type EventsWebhookEvent =
+export type UnwrapWebhookEvent =
   | MessageSentWebhookEvent
   | MessageReceivedWebhookEvent
   | MessageReadWebhookEvent
@@ -2010,6 +2022,6 @@ export declare namespace Webhooks {
     type ChatTypingIndicatorStartedWebhookEvent as ChatTypingIndicatorStartedWebhookEvent,
     type ChatTypingIndicatorStoppedWebhookEvent as ChatTypingIndicatorStoppedWebhookEvent,
     type PhoneNumberStatusUpdatedWebhookEvent as PhoneNumberStatusUpdatedWebhookEvent,
-    type EventsWebhookEvent as EventsWebhookEvent,
+    type UnwrapWebhookEvent as UnwrapWebhookEvent,
   };
 }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.25.0'; // x-release-please-version
+export const VERSION = '0.27.0'; // x-release-please-version

package/uploads.d.mts

@@ -1,2 +1,3 @@
+/** @deprecated Import from ./core/uploads instead */
 export * from "./core/uploads.mjs";
 //# sourceMappingURL=uploads.d.mts.map

package/uploads.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"uploads.d.mts","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":""}
+{"version":3,"file":"uploads.d.mts","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,mCAA+B"}

package/uploads.d.ts

@@ -1,2 +1,3 @@
+/** @deprecated Import from ./core/uploads instead */
 export * from "./core/uploads.js";
 //# sourceMappingURL=uploads.d.ts.map

package/uploads.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":""}
+{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,kCAA+B"}

package/uploads.mjs

@@ -1,2 +1,3 @@
+/** @deprecated Import from ./core/uploads instead */
 export * from "./core/uploads.mjs";
 //# sourceMappingURL=uploads.mjs.map

package/uploads.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"uploads.mjs","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":""}
+{"version":3,"file":"uploads.mjs","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,mCAA+B"}

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.25.0";
+export declare const VERSION = "0.27.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.25.0";
+export declare const VERSION = "0.27.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.25.0'; // x-release-please-version
+exports.VERSION = '0.27.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.25.0'; // x-release-please-version
+export const VERSION = '0.27.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map