Skip to main content

Overview

Corso webhooks send real-time HTTP POST notifications to your endpoint when important events occur—such as when a claim or shipping protection claim is created or finalized. You configure an endpoint URL in Corso Admin and subscribe to the events you need; Corso then delivers each event as a signed JSON payload. This lets you sync claims to your CRM, trigger internal workflows, or integrate with other systems without polling.

A typical flow looks like this:

Setup and verification

For step-by-step setup, HMAC verification code examples, retry behavior, and best practices, see the full guide at help.corso.com/integrations/webhooks.

Supported events​

TopicDescription
claim/createdFires when a new claim is created.
claim/updatedFires when a claim is updated (e.g. line items, status, or metadata).
claim/finalizedFires when a claim is finalized.
shipping_claim/createdFires when a new shipping protection claim is created.
shipping_claim/updatedFires when a shipping protection claim is updated.
shipping_claim/finalizedFires when a shipping protection claim is finalized.
registration/createdFires when a new product registration is created.

You can enable or disable each topic per webhook in Corso Admin. Claim topics (claim/*), shipping claim topics (shipping_claim/*), and registration topics (registration/*) each send different payload shapes—see Payload structure below.

Request headers​

Corso sends the same headers with every webhook request, regardless of topic:

HeaderDescription
Content-Typeapplication/json
X-Corso-Webhook-IdUnique delivery ID (use for idempotency).
X-Corso-Webhook-TimestampUnix timestamp in seconds (not included in HMAC signature; provided for optional replay attack prevention).
X-Corso-SignatureHMAC-SHA256 signature with algorithm prefix, e.g. sha256=<hex>.
X-Corso-Signature-SHA-256HMAC-SHA256 signature as a raw hex digest (no prefix). Use whichever header your platform prefers.
X-Corso-Webhook-TopicEvent topic (e.g. claim/created).
X-Corso-Api-VersionAPI version string.
X-Corso-Store-IdCorso store ID.

Use these headers for routing, idempotency, and signature verification. The request body (below) is the event-specific resource.

Source IDs​

Fields that hold an ID from the store's platform—those prefixed with source (such as sourceOrderId, sourceLineItemId, sourceCustomerId, and sourceProductId) along with productId and variantId on line items—use that platform's own identifiers. When the store's platform is Shopify, these are always Shopify's numeric legacy IDs (for example 7425696170134), never gid://shopify/... GraphQL IDs.

Payload structure​

The request body is the event-specific resource only (the data from the OAS webhook payload). Its shape depends on the topic; routing and metadata are in the request headers above.

Claim topics (claim/created, claim/updated, claim/finalized)​

The body is the full claim resource. See Get a claim in the Commerce API for the full schema.

Example:

{
  "storeId": 123,
  "claimId": 456789,
  "externalId": "1-123-1",
  "currencyCode": "USD",
  "claimType": "Return",
  "status": "In_Progress",
  "isInstantExchange": false,
  "wasCreatedFromRegistration": false,
  "customerEmail": "[email protected]",
  "customerName": "Jane Doe",
  "sourceCustomerId": "6843921785910",
  "shippingAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    "line1": "1901 W Madison St",
    "city": "Chicago",
    "stateOrProvinceCode": "IL",
    "postalCode": "60612",
    "countryCode": "US"
  },
  "billingAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    "line1": "1901 W Madison St",
    "city": "Chicago",
    "stateOrProvinceCode": "IL",
    "postalCode": "60612",
    "countryCode": "US"
  },
  "order": {
    "orderId": 14,
    "sourceOrderId": "7425696170134",
    "orderNumber": "1580",
    "orderName": "#1580",
    "createdOn": "2024-01-18T00:29:30.552Z"
  },
  "claimLineItems": [
    {
      "claimLineItemId": 108,
      "quantity": 1,
      "amount": 0,
      "requestedAmount": 0,
      "reason": "Wrong Size",
      "reasonDetail": "Too Small",
      "reasonCategory": "Wrong_Fit",
      "status": "Open",
      "statusDetail": "Pending_Review",
      "requestedResolutionMethod": "Variant_Exchange",
      "isShopNow": false,
      "customFields": [],
      "fees": [],
      "imageUrls": [],
      "noteFromCustomer": "",
      "sourceLineItem": {
        "lineItemId": 42,
        "sourceLineItemId": "38921234567890",
        "productId": "8234567890123",
        "variantId": "40123456789012",
        "sku": "SKU-ABC",
        "name": "Classic Tee - Blue / M",
        "options": [
          { "name": "Color", "value": "Blue" },
          { "name": "Size", "value": "M" }
        ],
        "quantity": 1
      },
      "variantExchangeLineItem": {
        "variantId": "40123456789013",
        "quantity": 1,
        "price": 25,
        "sku": "SKU-ABD",
        "title": "Classic Tee",
        "options": [
          { "name": "Color", "value": "Blue" },
          { "name": "Size", "value": "L" }
        ]
      }
    }
  ],
  "shipments": [],
  "tags": [],
  "feeAmountApplied": 0,
  "exchangeOrderShippingAmountApplied": 0,
  "returnShippingAmountApplied": 0,
  "shopNowIncentiveAmountApplied": 0,
  "createdOn": "2024-01-20T14:45:00.000Z",
  "updatedOn": "2024-01-20T14:45:00.000Z"
}

Once a claim is finalized, resolutionSummary.replacementOrders[].lineItems[].claimLineItemIds lists the claim line items each replacement line item fulfills.

Shipping claim topics (shipping_claim/created, shipping_claim/updated, shipping_claim/finalized)​

The body is the shipping protection claim resource. See Get a shipping claim in the Commerce API for the full schema.

Example:

{
  "shippingClaimId": 456789,
  "storeId": 123,
  "status": "Open",
  "reason": "Lost",
  "customerEmail": "[email protected]",
  "order": {
    "orderId": 14,
    "sourceOrderId": "7425696170134",
    "orderNumber": "1580",
    "createdOn": "2024-01-18T00:29:30.552Z"
  },
  "claimLineItems": [
    {
      "claimLineItemId": 108,
      "quantity": 1,
      "sourceLineItem": {
        "lineItemId": 42,
        "sourceLineItemId": "38921234567890",
        "productId": "8234567890123",
        "variantId": "40123456789012",
        "sku": "SKU-ABC",
        "name": "Classic Tee - Blue / M",
        "quantity": 1
      }
    }
  ],
  "currencyCode": "USD",
  "createdOn": "2024-01-20T14:45:00.000Z"
}

Registration topics (registration/created)​

The body is the product registration resource—registration ID, customer info, channel, line items, custom fields, and timestamps.

Example:

{
  "registrationId": 789012,
  "storeId": 123,
  "externalId": "REG-1580-1",
  "customerEmail": "[email protected]",
  "customerName": "Jane Doe",
  "channelName": "Online Store",
  "emailMarketingConsent": true,
  "emailMarketingConsentCollectedOn": "2024-01-20T14:45:00.000Z",
  "claims": [],
  "lineItems": [
    {
      "lineItemId": 42,
      "sourceLineItemId": "38921234567890",
      "productId": "8234567890123",
      "variantId": "40123456789012",
      "sku": "SKU-ABC",
      "name": "Classic Tee - Blue / M",
      "quantity": 1,
      "imgUrl": "https://cdn.example.com/products/classic-tee.jpg"
    }
  ],
  "createdOn": "2024-01-20T14:45:00.000Z"
}