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, e.g. sha256=<hex>.
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.

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:

{
  "claimId": 456789,
  "storeId": 123,
  "externalId": "1-123-1",
  "currencyCode": "USD",
  "claimType": "Return",
  "status": "In_Progress",
  "customerEmail": "[email protected]",
  "customerName": "Jane Doe",
  "customerAddress": {
    "line1": "1901 W Madison St",
    "city": "Chicago",
    "stateOrProvinceCode": "IL",
    "postalCode": "60612",
    "countryCode": "USA"
  },
  "order": {
    "orderId": 14,
    "sourceOrderId": "7425696170134",
    "orderNumber": "1580",
    "createdOn": "2024-01-18T00:29:30.552Z"
  },
  "claimLineItems": [
    {
      "claimLineItemId": 108,
      "quantity": 1,
      "amount": 49.99,
      "requestedAmount": 49.99,
      "reason": "Wrong Size",
      "status": "Open",
      "statusDetail": "Pending_Review",
      "requestedResolutionMethod": "Refund",
      "sourceLineItem": {
        "lineItemId": 42,
        "sourceLineItemId": "38921234567890",
        "productId": "8234567890123",
        "variantId": "40123456789012",
        "sku": "SKU-ABC",
        "name": "Classic Tee - Blue / M",
        "quantity": 1
      },
      "isShopNow": false
    }
  ],
  "shipments": [],
  "tags": [],
  "isInstantExchange": false,
  "feeAmountApplied": 0,
  "exchangeOrderShippingAmountApplied": 0,
  "returnShippingAmountApplied": 0,
  "createdOn": "2024-01-20T14:45:00.000Z",
  "updatedOn": "2024-01-20T14:45:00.000Z",
  "finalizedOn": null
}

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",
  "finalizedOn": null
}

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",
  "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"
}