Webhook request

Authentication and Processing

Webhooks sent from Extend require digital signature verification. Once verified, the webhooks can be processed for business logic.

The webhook payload is JSON.
The signature is sent as a signature header.
Extend's public key id is sent as the X-Extend-Key-Id header.
Extend's key id is also sent in the webhook request payload as kid. Confirm that the value of X-Extend-Key-Id and kid match.

As part of the verification flow, you will need to make an HTTP GET request to Extend's JWKS endpoint: https://api.helloextend.com/service-orders/oauth/keys

{{API_HOST}}/service-orders/oauth/keys
{
  "keys": [
    {
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "key_ops": [
        "sign",
        "verify"
      ],
      "kid": "b35edb9f-4be9-4cb4-9425-6f3d04ac9347",
      "n": "tvFPcO-lSUcW9n_dv45wfY0yF47CXZLICqS5kWIypfpP2NX4WRDK8c0bXx6g9P4n_UjJqyDsa-ocMil2dWRDn2oGCzrZLvk6bwerQfCij0Qvy92YZAWJ8r2QrQN69LZzrzCqpMbleclb4du5L46tIdWpOuWx9JWOD_F_HROyd26-SIUvrsLnk7pjSsRx1Bp9mw-qjIB2tEFCINrD3IDcFicPKMpWImhNA-Bukq3ZySzq2VvqAqmhif5EsLw4XWXOucM7YWLn5MfscRippwky94emVD4Hc3LaIYdjxcSMd9Gyr4vgEQU-sgj_hrBfjCabLEsfELIbrC4aPaNN1VTar91ErycEtmH5fNAhI7ka1YUFt5-AgvXDcPs4vnHuTX86TG_0IMhSxr-jvdarYJbTdbLU2-ViRSjIc3FSg4qjvxmyfJNXkwIWHy5Mh3kEK3GA573GofyCTjo20IwjNwhys0PdMnC9YXJQATPE4BvADaaA4UiKDeMfpOXA4Y6dgA9HDRVoA0RgNAycfHh0eIyjnOZjaU7napAxQjr7xqTw_8d8_MpCdAaAb70iL5pbbAtXpuhB27fvKNgvQGD3-X6idEbMYuJmZHzqDMfEmJROd4SjQl0OR5Lay5KpZyvjVsskh0GEbU_HR87UYP8FJn-avDhG6jU-HtSDJahACXeaS-s",
      "e": "AQAB"
    }
  ]
}

Parse the JSON response which contains an array of keys in JWK format. Find the specific key that matches the kid from the webhook payload.
Convert the JWK (JSON Web Key) to PEM format, which is required for most signature verification libraries. This typically involves using a crypto library to create a public key object from the JWK and exporting it in PEM format. Here is an example using the crypto Node module.

/**
 * Convert a JWK to PEM format
 *
 * @param jwk - The JWK object (the full key Object from the 'keys' array)
 * @returns PEM formatted key
 */
function jwkToPem(jwk: any): string {
  try {
    const publicKey = crypto.createPublicKey({
      key: jwk as unknown as NodeJsonWebKey,
      format: 'jwk',
    })
    return publicKey.export({ type: 'spki', format: 'pem' }).toString()
  } catch (error) {
    Log.error('Error converting JWK to PEM', error)
    throw error
  }
}

Verify the Digital Signature. Use a cryptographic library to verify that the signature was created using the private key corresponding to the public key. The verification should use the RSA-SHA256 algorithm. The signature is typically base64-encoded and needs to be decoded before verification.

import crypto from 'crypto'
/**
 * Returns true if signature verification passed
 *
 * @param body - Stringified body of the webhook
 * @param publicKey - Base64 encoded publicKey.
 * @param signature - Base64 encoded signature. Found in webhook ['signature'] header.
 * The signature found in the request header is Base64 encoded.
 * @returns true if the verification passed
 */
/**
 * Verify webhook signature using JWKS approach
 *
 * @param body - Stringified body of the webhook
 * @param signature - Base64 encoded signature from 'signature' header
 * @param keyId - Key ID from 'X-Extend-Key-Id' header (should match kid in payload)
 * @returns true if the verification passed
 */
async function verifyWebhookSignature(
  body: string,
  signature: string,
  keyId: string,
): Promise<boolean> {
  try {
    // 1. Fetch JWKS from Extend
    const jwksResponse = await fetch(
      'https://api-replacementssandbox.helloextend.com/service-orders/oauth/keys',
    )
    const jwks = await jwksResponse.json()

    // 2. Find the key that matches the keyId
    const key = jwks.keys.find((k: any) => k.kid === keyId)
    if (!key) {
      console.error('Key not found for kid:', keyId)
      return false
    }

    // 3. Convert JWK to PEM
    const publicKey = crypto.createPublicKey({
      key: key,
      format: 'jwk',
    })
    const pemKey = publicKey.export({ type: 'spki', format: 'pem' })

    // 4. Verify signature
    return crypto.verify(
      'RSA-SHA256',
      Buffer.from(body),
      pemKey,
      Buffer.from(signature, 'base64'),
    )
  } catch (e) {
    console.error('Signature verification failed:', e)
    return false
  }
}

// Example usage - JWKS approach (recommended)
const requestBody =
  '{"contractId":"66ab30c0-636a-4d46-a599-d56958a27a78","claimId":"052a0b5c-a726-4e81-8532-fcc8a439e60b","claimType":"extended_warranty","claimStatus":"approved","transactionId":"d152c12d-ebb9-4a69-b11b-0cf40e717d11","remainingLimitOfLiability":12999,"customer":{"name":"Paul L\'Astname","shippingAddress":{"city":"San Francisco","address1":"5333333335 Mission Street","provinceCode":"CA","countryCode":"USA","postalCode":"94121"},"phone":"555-535-5555","email":"alex.gunning+4a590efd-835a-49b8-a6dd-6ff331ab949d@extend.com"},"products":[{"title":"Rustic Soft Tuna","type":"product_protection","limitOfLiability":{"amount":12999},"lineItemId":"5cddd97e-f8f9-4743-bd6e-5e1c0158a37d","referenceId":"PRODUCT-REPLACE-1EwziVYmx1dMBKBg6Z3hxTCe7JHXDjuoMQ"}],"incident":{"failureType":"dropped","description":"BROKE PLZ HALP","occurredAt":1760140799999,"productCondition":"nonfunctional"},"reportedAt":1760130579776,"sendDate":1760130583057,"type":"claim_approved","url":"https://webhook.site/a19285f2-c57b-442c-89ed-0a5f9f297760","kid":"b35edb9f-4be9-4cb4-9425-6f3d04ac9347","coverageTerm":{"startDate":1760130470322,"endDate":1791666470322}}'
const signature =
  'lIUEeLFe36xOZuKT5M5XTf/mvWtdLl1yY1jh8kURUMUJeJ9D/FgkG85lpRhEjUrn7qkTtHQ2hzs493YnHi4YXmXLP1I/gJsyp8V619Cm4mX3RlUK1tg/tiuyrRc/KPorVYFCd7rk17fNnXJcj6iD9Gh7ZqE1fodh0bdakup0yGXpbggkhmmq5FSV4uGwHe/BPfpdGMOvLWgf56+SPMp6m4UV33guL+McLnbcxRuGewkIRGWKrnEyJm6ghmhZ6O8iu9coMPRdtVYaXCIwhKxxwi9NGNULsNl18theEB7w04ZArjJSBm19jejJaBMs4N9sJFhzaMma6Yl7BQX9DZ6isXcJYM2Qb4tMg4e4hEHPEH0iQknHID5ZBMSj3+y7oIZZtbQ7gujXL8XFfHSzV+NBXLFXINe8RrSpODTacoi31qhfd08yiOtvwioUugQzCuGRHtynS5Jezjy0pk/34f10MMJu/eMY1p4VS20Ex+g0yPzSAV0XfqBob9uAEiuT7LM30f99NVhChmtjQ4F4f0VIfdgNbCQzzEDM61Oek7KwLVnw3/qstTPVC8ZPhcoSt8nzsBIGNiKnV7vz1KBi4CyLRB6dt/emxcDEPWw1c93C3Rz+/pwGt+ApE0/lYauJnOJ6fW59Mq0KAEaIp6fwkmbuHO7Zx6Rw64vXzktqr5GhTAA='
const keyId = 'b35edb9f-4be9-4cb4-9425-6f3d04ac9347' // From X-Extend-Key-Id header

// Verify using modern approach
const isValid = await verifyWebhookSignature(requestBody, signature, keyId)
if (isValid) {
  console.log('Signature is valid!')
} else {
  console.log('Signature is not valid.')
}

If the signature verification succeeds; process the webhook. If verification fails; reject the webhook.

Complete Example

Here's a full example of handling webhooks built with AWS Lambda using the JWKS approach:

import crypto from 'crypto'
import fetch from 'node-fetch'

const lambda = async event => {
  const { headers, body } = event

  // Extract signature and key ID from headers
  const signature = headers['signature']
  const keyId = headers['X-Extend-Key-Id']

  console.log('webhook received')
  if (!signature || !keyId) {
    console.log('Webhook missing required headers. Unauthorized')
    return { statusCode: 401 }
  }

  console.log('attempting to verify RSA-SHA256 signature using JWKS')

  const verification = await verifyWebhookSignature(body, signature, keyId)
  if (!verification) {
    console.log('Unable to verify signature. Unauthorized')
    return { statusCode: 401 }
  }

  console.log('signature verification passed')

  // Parse the webhook payload
  const webhookData = JSON.parse(body)

  // Handle different webhook types
  if (webhookData.type === 'assign') {
    console.log(
      'Processing assigned webhook for service order:',
      webhookData.serviceOrderId,
    )
    // Process assigned webhook logic here
  } else if (webhookData.type === 'return_approved') {
    console.log(
      'Processing return approved webhook for service order:',
      webhookData.serviceOrderId,
    )
    // Process return approved webhook logic here
  }

  return { statusCode: 200 }
}

/**
 * Verify webhook signature using JWKS approach
 *
 * @param body - Stringified body of the webhook
 * @param signature - Base64 encoded signature from 'signature' header
 * @param keyId - Key ID from 'X-Extend-Key-Id' header (should match kid in payload)
 * @returns true if the verification passed
 */
async function verifyWebhookSignature(
  body: string,
  signature: string,
  keyId: string,
): Promise<boolean> {
  try {
    // 1. Fetch JWKS from Extend
    const jwksResponse = await fetch(
      'https://api.helloextend.com/service-orders/oauth/keys',
    )
    const jwks = await jwksResponse.json()

    // 2. Find the key that matches the keyId
    const key = jwks.keys.find((k: any) => k.kid === keyId)
    if (!key) {
      console.error('Key not found for kid:', keyId)
      return false
    }

    // 3. Convert JWK to PEM
    const publicKey = crypto.createPublicKey({
      key: key,
      format: 'jwk',
    })
    const pemKey = publicKey.export({ type: 'spki', format: 'pem' })

    // 4. Verify signature
    return crypto.verify(
      'RSA-SHA256',
      Buffer.from(body),
      pemKey,
      Buffer.from(signature, 'base64'),
    )
  } catch (e) {
    console.error('Signature verification failed:', e)
    return false
  }
}

Webhook Request Body

Webhook Types and Usage

Extend sends three types of webhooks to servicers:

Assigned Webhook (type: "assign"): Sent when a service order is assigned to a servicer for repair/replacement
Return Approved Webhook (type: "return_approved"): Sent when a return/refund has been approved, this will be triggered after the customer has shipped their product back if they are required to return it, depending on the configuration. The configuration may approve the refund based on product scanned in transit, marked as delivered, or after manual inspection.
Shipping Resolution Approved Webhook (type: "shipping_resolution_approved): Sent when a shipping resolution service order has been approved for refund or replacement. This status may happen after a customer ships their product back, if this is required depending on your configuration.

All webhook types include the kid field for signature verification and follow the same authentication process.

Assigned Webhook

interface AssignedWebhook {
  contractId: string
  contractPurchaseDate: number
  productDeliveryDate?: number
  claimId: string
  serviceOrderId: string
  serviceAmountAuthorized?: number
  orderNumber?: string
  customerName: string
  customerEmail: string
  customerShippingAddress: Address
  customerPhoneNumber?: string
  productDetails: ProductDetails[]
  failureType: string
  failureDescription?: string
  incident: {
    FailureType: string
    // Can include additional properties
  }
  sendDate: number
  servicerId: string
  url: string
  transactionId: string
  type: string
  kid: string // Key ID for signature verification
}

interface ProductDetails {
  productReferenceId: string
  sku?: string
  productListPrice?: number // In cents
  productPurchasePrice?: number // In cents
  productVertical?: string
}

interface Address {
  address1: string
  address2?: string
  city: string
  countryCode: string
  postalCode: string
  provinceCode?: string
}

Example

{
  "serviceOrderId": "4319c6c7-48aa-4086-a114-b63d9161aa18",
  "claimId": "09c6dfc3-3e29-4b3d-a83a-19d9b2c5971a",
  "contractId": "15e0abb5-6b96-4f68-827d-ff962027221f",
  "servicerId": "3855a17d-3b61-44c9-b45c-43469e9f1d0a",
  "customerName": "Customer Name",
  "customerEmail": "customer@email.com",
  "contractPurchaseDate": 1654117627000,
  "customerShippingAddress": {
    "address2": "Ste 1",
    "city": "San Francisco",
    "address1": "1 Main St",
    "provinceCode": "CA",
    "countryCode": "US",
    "postalCode": "11111"
  },
  "customerPhoneNumber": "111-111-1111",
  "productDetails": [
    {
      "productReferenceId": "referenceId",
      "productListPrice": 25199,
      "productPurchasePrice": 25199
    }
  ],
  "failureType": "electricalFailure",
  "failureDescription": "The description of the failure.",
  "incident": {
    "FailureType": "electricalFailure"
  },
  "sendDate": 1690910629602,
  "url": "https://servicer-webhook-url/post-webhook",
  "transactionId": "b16a3b34-636c-4941-b69b-8eaf57b62c9f",
  "type": "assign",
  "kid": "b35edb9f-4be9-4cb4-9425-6f3d04ac9347"
}

Return Approved Webhook

interface ReturnApprovedWebhook {
  type: 'return_approved'
  kid: string // Key ID for signature verification
  claimId: string
  serviceOrderId: string
  orderId: string
  claimDetailsUrl: string
  customerName: string
  customerEmail: string
  customerShippingAddress: Address
  customerPhoneNumber?: string
  productDetails: ProductDetails[]
  failureType: string
  failureDescription?: string
  incident: {
    failureType: string
    // Can include additional properties
  }
  sendDate: number
  url: string
  transactionId: string
  refundAmount: number // In cents
  refundOption: 'original_tender' | 'store_credit'
  orderPurchaseDate?: number
  productDeliveryDate?: number
  storeId?: string
  returnShipment?: ReturnShipment
  returnRequired?: boolean
  costDetails?: CostDetails
  rmaNumber?: string
}

interface ProductDetails {
  productReferenceId: string
  sku?: string
  productListPrice?: number // In cents
  productPurchasePrice?: number // In cents
  productVertical?: string
  lineItemId?: string
  lineItemTransactionId?: string
  title?: string
}

interface Address {
  address1: string
  address2?: string
  city: string
  countryCode: string
  postalCode: string
  provinceCode?: string
}

interface CostDetails {
  totalAmount?: number // In cents
  currencyCode?: string
  productCosts: ProductCost[]
  tax?: number // In cents
  returnCost?: number // In cents
  shippingCost?: number // In cents
}

interface ProductCost {
  lineItemId: string
  itemValue: number // In cents
  contractValue?: number // In cents
  quantity: number
  discountValue?: number // In cents
}

interface ReturnShipment {
  shipmentId: string
  carrier: string
  broker: string
  destination: Address
  origin: Address
  status: string
  trackingNumber?: string
  shippedAt?: number
  estimatedDeliveryAt?: number
  deliveredAt?: number
}

Example

const returnApprovedWebhookExample = {
  type: 'return_approved',
  kid: 'b35edb9f-4be9-4cb4-9425-6f3d04ac9347',
  claimDetailsUrl: 'https://merchants.extend.com/claims/abc123-def456',
  orderId: 'ORD-2024-789012',
  claimId: 'abc123-def456-ghi789',
  serviceOrderId: 'so-111222-333444',
  customerName: 'John Doe',
  customerEmail: 'john.doe@example.com',
  customerShippingAddress: {
    address1: '456 Oak Avenue',
    city: 'Austin',
    provinceCode: 'TX',
    countryCode: 'USA',
    postalCode: '78701'
  },
  productDetails: [
    {
      productReferenceId: 'PROD-RETURN-54321',
      sku: 'SKU-LAMP-002',
      productListPrice: 12999,
      productPurchasePrice: 11999,
      lineItemId: 'LI-002',
      title: 'Modern Desk Lamp'
    }
  ],
  failureType: 'defective',
  failureDescription: 'Light flickers intermittently after 2 weeks of use',
  incident: {
    failureType: 'defective',
    description: 'Lamp flickers and sometimes does not turn on',
    occurredAt: 1732924800000
  },
  sendDate: 1733270400000,
  url: 'https://yourstore.com/webhooks/extend-return',
  transactionId: 'txn-return-887766',
  refundAmount: 11999,            
  refundOption: 'original_tender',  
  rmaNumber: 'RMA-2024-55443'      
}

Shipping Resolution Approved Webhook

interface ShippingResolutionApprovedWebhook {
  type: 'shipping_resolution_approved'
  kid: string // Key ID for signature verification
  claimId: string
  serviceOrderId: string
  orderId: string
  claimDetailsUrl: string
  customerName: string
  customerEmail: string
  customerShippingAddress: Address
  customerPhoneNumber?: string
  productDetails: ProductDetails[]
  failureType: string
  failureDescription?: string
  incident: {
    failureType: string
    // Can include additional properties
  }
  sendDate: number
  url: string
  transactionId: string
  costDetails: CostDetails
  orderPurchaseDate?: number
  productDeliveryDate?: number
  storeId?: string
  returnShipment?: ReturnShipment
  returnRequired?: boolean
  fulfillmentMethod?: 'automated_replacement' | 'store_credit' | 'original_tender' | 'manual'
  rmaNumber?: string
}

interface ProductDetails {
  productReferenceId: string
  sku?: string
  productListPrice?: number // In cents
  productPurchasePrice?: number // In cents
  productVertical?: string
  lineItemId?: string
  lineItemTransactionId?: string
  title?: string
}

interface Address {
  address1: string
  address2?: string
  city: string
  countryCode: string
  postalCode: string
  provinceCode?: string
}

interface CostDetails {
  totalAmount: number // In cents
  currencyCode: string
  productCosts: ProductCost[]
  tax?: number // In cents
  returnCost?: number // In cents
  shippingCost?: number // In cents
}

interface ProductCost {
  lineItemId: string
  itemValue: number // In cents
  contractValue?: number // In cents
  quantity: number
  discountValue?: number // In cents
}

interface ReturnShipment {
  shipmentId: string
  carrier: string
  broker: string
  destination: Address
  origin: Address
  status: string
  trackingNumber?: string
  shippedAt?: number
  estimatedDeliveryAt?: number
  deliveredAt?: number
}

Example

{
  "type": "shipping_resolution_approved",
  "kid": "b35edb9f-4be9-4cb4-9425-6f3d04ac9347",
  "claimDetailsUrl": "https://merchants.extend.com/claims/7b67180d-0ae6-4d81-a0ca-d7eeda41870e",
  "orderId": "ORD-2024-123456",
  "claimId": "7b67180d-0ae6-4d81-a0ca-d7eeda41870e",
  "serviceOrderId": "73752710-8cdf-4fe3-8327-6936fa3badd6",
  "customerName": "Jane Smith",
  "customerEmail": "jane.smith@example.com",
  "customerShippingAddress": {
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "San Francisco",
    "provinceCode": "CA",
    "countryCode": "USA",
    "postalCode": "94105"
  },
  "productDetails": [
    {
      "productReferenceId": "PROD-SP-12345",
      "sku": "SKU-HEADPHONES-001",
      "productListPrice": 7999,
      "productPurchasePrice": 6999,
      "productVertical": "electronics",
      "lineItemId": "LI-001",
      "lineItemTransactionId": "TXN-LI-001",
      "title": "Wireless Bluetooth Headphones"
    }
  ],
  "failureType": "lost_in_transit",
  "failureDescription": "Package never arrived",
  "incident": {
    "failureType": "lost_in_transit",
    "description": "Package marked delivered but not received",
    "occurredAt": 1733011200000
  },
  "sendDate": 1733270400000,
  "url": "https://yourstore.com/webhooks/extend",
  "transactionId": "63815176-f685-44ca-8180-fb13e39d5d04",
  "costDetails": {
    "totalAmount": 6999,
    "currencyCode": "USD",
    "productCosts": [
      {
        "lineItemId": "LI-001",
        "itemValue": 6999,
        "contractValue": 399,
        "quantity": 1
      }
    ],
    "shippingCost": 899
  },
  "orderPurchaseDate": 1732492800000,
  "storeId": "store-12345",
  "customerPhoneNumber": "555-123-4567",
  "returnRequired": false,
  "fulfillmentMethod": "product_replacement",
  "rmaNumber": "RMA-2024-78901"
}

Webhooks should be responded to with a status code 200. All requests that do not receive a 200 will be retried every hour for 48 hours.

Legacy Method For Signature Verification

Public Key endpoint

;/ GET /service-orders/public-key

interface ResponseBody {
  key: string
}

The public key will be base64 encoded.

Signature

The webhook request will come with a signature header. The webhook signature will be base64 encoded. The signature will be what is used to verify that the message has not been tampered with or altered. Any message where the signature cannot be verified should be discarded. Use a SHA256 signature verification library to verify the message.

An example of how to verify a digital signature.

import crypto from 'crypto'
/**
 * Returns true if signature verification passed
 *
 * @param body - Stringified body of the webhook
 * @param publicKey - Base64 encoded publicKey. Public key can be fetched at GET /service-orders/public-key
 * The public key endpoint returns the key Base64 encoded.
 * @param signature - Base64 encoded signature. Found in webhook ['signature'] header.
 * The signature found in the request header is Base64 encoded.
 * @returns true if the verification passed
 */
function verifyDigitalSignature(
  body: string,
  publicKey: string,
  signature: string,
): boolean {
  try {
    return crypto.verify(
      'RSA-SHA256',
      Buffer.from(body),
      Buffer.from(publicKey, 'base64'),
      Buffer.from(signature, 'base64'),
    )
  } catch (e) {
    return false
  }
}

// Example usage
const publicKey =
  'LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQ0lqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FnOEFNSUlDQ2dLQ0FnRUF0dkZQY08rbFNVY1c5bi9kdjQ1dwpmWTB5RjQ3Q1haTElDcVM1a1dJeXBmcFAyTlg0V1JESzhjMGJYeDZnOVA0bi9VakpxeURzYStvY01pbDJkV1JECm4yb0dDenJaTHZrNmJ3ZXJRZkNpajBRdnk5MllaQVdKOHIyUXJRTjY5TFp6cnpDcXBNYmxlY2xiNGR1NUw0NnQKSWRXcE91V3g5SldPRC9GL0hST3lkMjYrU0lVdnJzTG5rN3BqU3NSeDFCcDltdytxaklCMnRFRkNJTnJEM0lEYwpGaWNQS01wV0ltaE5BK0J1a3EzWnlTenEyVnZxQXFtaGlmNUVzTHc0WFdYT3VjTTdZV0xuNU1mc2NSaXBwd2t5Cjk0ZW1WRDRIYzNMYUlZZGp4Y1NNZDlHeXI0dmdFUVUrc2dqL2hyQmZqQ2FiTEVzZkVMSWJyQzRhUGFOTjFWVGEKcjkxRXJ5Y0V0bUg1Zk5BaEk3a2ExWVVGdDUrQWd2WERjUHM0dm5IdVRYODZURy8wSU1oU3hyK2p2ZGFyWUpiVApkYkxVMitWaVJTakljM0ZTZzRxanZ4bXlmSk5Ya3dJV0h5NU1oM2tFSzNHQTU3M0dvZnlDVGpvMjBJd2pOd2h5CnMwUGRNbkM5WVhKUUFUUEU0QnZBRGFhQTRVaUtEZU1mcE9YQTRZNmRnQTlIRFJWb0EwUmdOQXljZkhoMGVJeWoKbk9aamFVN25hcEF4UWpyN3hxVHcvOGQ4L01wQ2RBYUFiNzBpTDVwYmJBdFhwdWhCMjdmdktOZ3ZRR0QzK1g2aQpkRWJNWXVKbVpIenFETWZFbUpST2Q0U2pRbDBPUjVMYXk1S3BaeXZqVnNza2gwR0ViVS9IUjg3VVlQOEZKbithCnZEaEc2alUrSHRTREphaEFDWGVhUytzQ0F3RUFBUT09Ci0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQ=='

const requestBody =
  '{"serviceOrderId":"73752710-8cdf-4fe3-8327-6936fa3badd6","claimId":"7b67180d-0ae6-4d81-a0ca-d7eeda41870e","contractId":"770e5f9d-fb2d-4c53-9137-cbb647d037f5","servicerId":"26db19a3-d9db-4ad4-9575-b7ca2f6e990a","customerName":"Paul Name","customerEmail":"alex.gunning@extend.com","contractPurchaseDate":1655668093818,"customerShippingAddress":{"city":"San Francisco","address1":"533 Mission Street","provinceCode":"CA","countryCode":"USA","postalCode":"94105"},"customerPhoneNumber":"555-535-5555","productDetails":[{"productReferenceId":"PRODUCT-REPAIR-385UmuLNaUqVmpohrmnvMqrncttQCz","productListPrice":25199,"productPurchasePrice":25199}],"failureType":"webhook parse","failureDescription":"webhook","incident":{"failureType":"electricalFailure","description":"BROKE PLZ HALP","occurredAt":1695152893819,"FailureType":"webhook parse","FailureDescription":"webhook","productCondition":"nonfunctional"},"sendDate":1695152952396,"url":"https://webhook.site/70a09585-f934-4b01-855b-0869e5e19752","transactionId":"63815176-f685-44ca-8180-fb13e39d5d04","type":"assign"}'
const signature =
  'JJbRyjmmylP4GJtNCT7wANYVMkmUYENuX13sXqMjbAUcfidBBix/hzCjnoycg6lCT1Ktny2OnmixEHQAwNFOuReTlid+AFvCQnQ0nA+aUjvD3JSYCLLE2SOuvbZ7/Q/fQZNnFrDUX6MXcYkuoNLUmKRagG5uq0UyIEtWgfyLtGJQlZ91KXJkvZsFQu+AO5dFiDceJA+IW11sCN5e/9gKWuHxzxwKepvA8S0lyPwQWYqk1V/O/bV5s5uD5zrI6Wndd8Yq7ejYsWd6ZeHbjrcTbbr35lKsTcpoLxtBjD+H/1X5+pYAPlW7ymLWpPxEAug8tnpzy5HVMtwNZ3br8S5afC9BgR7abGcfa3PjyYvM1tk6+JfCPLa9gIJShu1+eXTq0GUQnxu/0bL/ihnwadHlFZyLVzmRjBkPrsuQsM6KTvXS5Gw+BGo+zy/p7iFUFHws1r6zZNONe0ZxTudpDgGN7IoXmvyj7OOJ7VyGROggB0Ptu2iiNz81uTT1M9z+QCR2pa9E+a6fTWTZIXP86acb8HuKDb8Rd9wkU4G609aZc3QHX0ANKIFSWqhz9WDh0XZgT8daMuda+TmtI4NkTS7j9yQLqvbYQ1W2RpCKVBLgXCgiylBoHfRWFZ/dlOdkojBWaFnWa8ytU69IHFgVAd4V4RVPgjNyWgwovtQtiAvpT3o='

if (verifyDigitalSignature(signature, publicKey, requestBody)) {
  console.log('Signature is valid!')
} else {
  console.log('Signature is not valid.')
}

Full featured example of handling webhook built with AWS lambda.

import crypto from 'crypto'
import fetch from 'node-fetch'

const lambda = async event => {
  const { headers, body } = event
  // Signature is a base64 encoded string in header 'siganture'
  const signature = headers['signature']

  console.log('webhook received')
  if (!signature) {
    console.log('Webhook does not contain signature. Unauthorized')
    return { statusCode: 401 }
  }
  // Public Key returned as base64 encoded string
  const publicKey = await getPublicKey()
  console.log('attempting to verify RSA-SHA256 signature')

  const verification = verifyDigitalSignature(body, publicKey, signature)
  if (!verification) {
    console.log('Unable to verify signature. Unauthorized')
    return { statusCode: 401 }
  }

  console.log('signature verification passed')
  return { statusCode: 200 }
}

/**
 * Returns true if signature verification passed
 *
 * @remarks
 * The crypto package is a built-in Node module
 *
 * @param body - Stringified body of the webhook
 * @param publicKey - Base64 encoded publicKey. Public key can be fetched at GET /service-orders/public-key
 * @param signature - Base64 encoded signature. Found in webhook ['signature'] header.
 * @returns true if the verification passed
 */
function verifyDigitalSignature(
  body: string,
  publicKey: string,
  signature: string,
): boolean {
  try {
    return crypto.verify(
      'RSA-SHA256',
      Buffer.from(body),
      Buffer.from(publicKey, 'base64'),
      Buffer.from(signature, 'base64'),
    )
  } catch (e) {
    console.log(e)
    return false
  }
}

async function getPublicKey(): Promise<string> {
  console.log('Getting Extend Public Key')
  const API_HOST = 'https://api.helloextend.com/'
  const url = `${API_HOST}/service-orders/public-key`
  const publicKeyResponse = await fetch(url, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
    },
  })
  const key = (await publicKeyResponse.json()).key
  if (!key) {
    throw new Error('Unable to parse public key')
  }
  return key
}