@linqapp/sdk 0.24.2 → 0.26.0

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)
  *
- * 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.
+ * Still sent on every delivery for backwards compatibility. Existing verification code
+ * using these headers continues to work — no changes required.
  *
- * **Signature Construction:**
+ * | 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) |
  *
- * The signature is computed over a concatenation of the timestamp and payload:
+ * ## Signing Secrets
  *
- * ```
- * {timestamp}.{payload}
- * ```
+ * Signing secrets use the Standard Webhooks format: a `whsec_` prefix followed
+ * by base64-encoded random bytes (e.g., `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw7Jxx2Oll+OE=`).
+ *
+ * Strip the `whsec_` prefix and base64-decode the remainder to get the raw key bytes.
+ *
+ * ## 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:
  *
- * Where:
- * - `timestamp` is the value from the `X-Webhook-Timestamp` header
- * - `payload` is the raw JSON request body (exact bytes, not re-serialized)
+ * **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(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)
+ * 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):**
@@ -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
@@ -142,6 +187,20 @@ export class WebhookSubscriptions extends APIResource {
     return this._client.post('/v3/webhook-subscriptions', { body, ...options });
   }
 
+  /**
+   * Retrieve all webhook subscriptions for the authenticated partner. Returns a list
+   * of active and inactive subscriptions with their configuration and status.
+   *
+   * @example
+   * ```ts
+   * const webhookSubscriptions =
+   *   await client.webhookSubscriptions.list();
+   * ```
+   */
+  list(options?: RequestOptions): APIPromise<WebhookSubscriptionListResponse> {
+    return this._client.get('/v3/webhook-subscriptions', options);
+  }
+
   /**
    * Retrieve details for a specific webhook subscription including its target URL,
    * subscribed events, and current status.
@@ -184,20 +243,6 @@ export class WebhookSubscriptions extends APIResource {
     return this._client.put(path`/v3/webhook-subscriptions/${subscriptionID}`, { body, ...options });
   }
 
-  /**
-   * Retrieve all webhook subscriptions for the authenticated partner. Returns a list
-   * of active and inactive subscriptions with their configuration and status.
-   *
-   * @example
-   * ```ts
-   * const webhookSubscriptions =
-   *   await client.webhookSubscriptions.list();
-   * ```
-   */
-  list(options?: RequestOptions): APIPromise<WebhookSubscriptionListResponse> {
-    return this._client.get('/v3/webhook-subscriptions', options);
-  }
-
   /**
    * Delete a webhook subscription.
    *

package/src/resources/webhooks.ts

@@ -794,7 +794,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 +1638,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 +1715,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 +1904,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.

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.24.2'; // x-release-please-version
+export const VERSION = '0.26.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.24.2";
+export declare const VERSION = "0.26.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.24.2'; // x-release-please-version
+exports.VERSION = '0.26.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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