@linqapp/sdk 0.25.0 → 0.26.0

package/resources/webhook-events.d.ts

@@ -14,55 +14,82 @@ import { RequestOptions } from "../internal/request-options.js";
  *
  * ## 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):**
@@ -70,16 +97,28 @@ import { RequestOptions } from "../internal/request-options.js";
  * ```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; }
+ *   });
  * }
  * ```
  *
@@ -105,12 +144,12 @@ export declare class WebhookEvents extends APIResource {
  * `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025
  * subscription will not produce any deliveries.
  */
-export type WebhookEventType = 'message.sent' | 'message.received' | 'message.read' | 'message.delivered' | 'message.failed' | 'message.edited' | 'reaction.added' | 'reaction.removed' | 'participant.added' | 'participant.removed' | 'chat.created' | 'chat.group_name_updated' | 'chat.group_icon_updated' | 'chat.group_name_update_failed' | 'chat.group_icon_update_failed' | 'chat.typing_indicator.started' | 'chat.typing_indicator.stopped' | 'phone_number.status_updated' | 'call.initiated' | 'call.ringing' | 'call.answered' | 'call.ended' | 'call.failed' | 'call.declined' | 'call.no_answer';
+export type WebhookEventType = 'message.sent' | 'message.received' | 'message.read' | 'message.delivered' | 'message.failed' | 'message.edited' | 'reaction.added' | 'reaction.removed' | 'participant.added' | 'participant.removed' | 'chat.created' | 'chat.group_name_updated' | 'chat.group_icon_updated' | 'chat.group_name_update_failed' | 'chat.group_icon_update_failed' | 'chat.typing_indicator.started' | 'chat.typing_indicator.stopped' | 'phone_number.status_updated' | 'call.initiated' | 'call.ringing' | 'call.answered' | 'call.ended' | 'call.failed' | 'call.declined' | '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/resources/webhook-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-events.d.ts","sourceRoot":"","sources":["../src/resources/webhook-events.ts"],"names":[],"mappings":"OAEO,EAAE,WAAW,EAAE;OACf,EAAE,UAAU,EAAE;OACd,EAAE,cAAc,EAAE;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAC5C;;;;OAIG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,wBAAwB,CAAC;CAGrE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,kBAAkB,GAClB,cAAc,GACd,mBAAmB,GACnB,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,mBAAmB,GACnB,qBAAqB,GACrB,cAAc,GACd,yBAAyB,GACzB,yBAAyB,GACzB,+BAA+B,GAC/B,+BAA+B,GAC/B,+BAA+B,GAC/B,+BAA+B,GAC/B,6BAA6B,GAC7B,gBAAgB,GAChB,cAAc,GACd,eAAe,GACf,YAAY,GACZ,aAAa,GACb,eAAe,GACf,gBAAgB,CAAC;AAErB,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,OAAO,EAAE,0DAA0D,CAAC;IAEpE;;OAEG;IACH,MAAM,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;CACjC;AAED,MAAM,CAAC,OAAO,WAAW,aAAa,CAAC;IACrC,OAAO,EACL,KAAK,gBAAgB,IAAI,gBAAgB,EACzC,KAAK,wBAAwB,IAAI,wBAAwB,GAC1D,CAAC;CACH"}
+{"version":3,"file":"webhook-events.d.ts","sourceRoot":"","sources":["../src/resources/webhook-events.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,4BAAyB;AAC/C,OAAO,EAAE,UAAU,EAAE,+BAA4B;AACjD,OAAO,EAAE,cAAc,EAAE,uCAAoC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+HG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAC5C;;;;OAIG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,wBAAwB,CAAC;CAGrE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,kBAAkB,GAClB,cAAc,GACd,mBAAmB,GACnB,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,mBAAmB,GACnB,qBAAqB,GACrB,cAAc,GACd,yBAAyB,GACzB,yBAAyB,GACzB,+BAA+B,GAC/B,+BAA+B,GAC/B,+BAA+B,GAC/B,+BAA+B,GAC/B,6BAA6B,GAC7B,gBAAgB,GAChB,cAAc,GACd,eAAe,GACf,YAAY,GACZ,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,0BAA0B,GAC1B,0BAA0B,CAAC;AAE/B,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,OAAO,EAAE,iDAAiD,CAAC;IAE3D;;OAEG;IACH,MAAM,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;CACjC;AAED,MAAM,CAAC,OAAO,WAAW,aAAa,CAAC;IACrC,OAAO,EACL,KAAK,gBAAgB,IAAI,gBAAgB,EACzC,KAAK,wBAAwB,IAAI,wBAAwB,GAC1D,CAAC;CACH"}

package/resources/webhook-events.js

@@ -16,55 +16,82 @@ const resource_1 = require("../core/resource.js");
  *
  * ## 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):**
@@ -72,16 +99,28 @@ const resource_1 = require("../core/resource.js");
  * ```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; }
+ *   });
  * }
  * ```
  *

package/resources/webhook-events.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-events.js","sourceRoot":"","sources":["../src/resources/webhook-events.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAI/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,MAAa,aAAc,SAAQ,sBAAW;IAC5C;;;;OAIG;IACH,IAAI,CAAC,OAAwB;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;CACF;AATD,sCASC"}
+{"version":3,"file":"webhook-events.js","sourceRoot":"","sources":["../src/resources/webhook-events.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAI/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+HG;AACH,MAAa,aAAc,SAAQ,sBAAW;IAC5C;;;;OAIG;IACH,IAAI,CAAC,OAAwB;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;CACF;AATD,sCASC"}

package/resources/webhook-events.mjs

@@ -13,55 +13,82 @@ import { APIResource } from "../core/resource.mjs";
  *
  * ## 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):**
@@ -69,16 +96,28 @@ import { APIResource } from "../core/resource.mjs";
  * ```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; }
+ *   });
  * }
  * ```
  *

package/resources/webhook-events.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-events.mjs","sourceRoot":"","sources":["../src/resources/webhook-events.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;AAItB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC5C;;;;OAIG;IACH,IAAI,CAAC,OAAwB;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;CACF"}
+{"version":3,"file":"webhook-events.mjs","sourceRoot":"","sources":["../src/resources/webhook-events.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAI/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+HG;AACH,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC5C;;;;OAIG;IACH,IAAI,CAAC,OAAwB;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;CACF"}