Cloud Bridge Webhooks

Webhook endpoint

All store webhooks are sent to a single endpoint pattern:

Webhook URL

POST /api/webhooks/<provider>/<integrationId>

Where:

<provider> is one of: shopify, woocommerce, or generic
<integrationId> is the unique ID of your store integration

Signature verification

Cloud Bridge verifies the authenticity of incoming webhooks using HMAC signatures. The signature header differs by provider:

Provider	Signature header	Algorithm
Shopify	`X-Shopify-Hmac-Sha256`	HMAC-SHA256 (Base64)
WooCommerce	`X-WC-Webhook-Signature`	HMAC-SHA256 (Base64)
Generic	`X-Webhook-Signature` or `X-NDSP-Signature`	HMAC-SHA256 (Hex, prefixed with `sha256=`)

Important: Webhooks with invalid or missing signatures are rejected with a 401 response. Always use the signing secret provided when you created the integration.

Shopify payload

Shopify sends the full order object. Cloud Bridge extracts line items and the customer's NDSP username from the order note or note attributes.

Shopify order webhook (relevant fields)

{
  "id": 5678901234,
  "order_number": 1042,
  "email": "customer@example.com",
  "note": "NDSP username: cortex_user_42",
  "note_attributes": [
    { "name": "ndsp_username", "value": "cortex_user_42" }
  ],
  "line_items": [
    {
      "sku": "STORM-LEAD-V2",
      "product_id": 7891234567890,
      "variant_id": 43210987654321,
      "title": "Storm Drive Lead Preset",
      "quantity": 1
    }
  ]
}

Username extraction: Cloud Bridge checks note_attributes for a field named ndsp_username, cortex_username, or neural_dsp_username. If not found, it falls back to parsing the note field.

WooCommerce payload

WooCommerce sends the full order object. Cloud Bridge extracts line items and looks for the NDSP username in order meta fields.

WooCommerce order webhook (relevant fields)

{
  "id": 1234,
  "order_key": "wc_order_abc123",
  "billing": {
    "email": "customer@example.com"
  },
  "meta_data": [
    { "key": "ndsp_username", "value": "cortex_user_42" }
  ],
  "line_items": [
    {
      "sku": "STORM-LEAD-V2",
      "product_id": 567,
      "variation_id": 890,
      "name": "Storm Drive Lead Preset",
      "quantity": 1
    }
  ]
}

Generic payload

The generic provider accepts a simplified JSON structure. Use this when integrating a custom store or platform.

Generic webhook payload

{
  "orderId": "order-1234",
  "customerEmail": "fan@music.com",
  "targetUsername": "cortex_user_42",
  "items": [
    {
      "sku": "STORM-LEAD-V2",
      "productId": "prod_123",
      "title": "Storm Drive Lead Preset",
      "quantity": 1
    }
  ]
}

Field	Type	Required	Description
`orderId`	string	Yes	Unique order identifier (used for deduplication)
`customerEmail`	string	No	Customer's email for reference
`targetUsername`	string	Yes	Customer's Cortex Cloud username
`items`	array	Yes	List of purchased items to match against item mappings
`items[].sku`	string	No*	Product SKU
`items[].productId`	string	No*	Product ID
`items[].title`	string	No*	Product title
`items[].quantity`	number	No	Quantity purchased (default: 1)

* At least one identifier (sku, productId, or title) must be present to match an item mapping.

Webhook responses

Cloud Bridge responds to webhooks synchronously:

Status	Meaning
`202`	Webhook accepted and delivery queued
`400`	Invalid payload or missing required fields
`401`	Invalid or missing webhook signature
`404`	Integration not found
`500`	Internal processing error

Retry behavior

Deliveries that fail due to transient errors or wait for Cortex Cloud friendship are automatically retried. The delivery queue processes up to 5 jobs per minute.

You can also manually retry a failed delivery from the Integrations page in your dashboard. For deliveries that failed due to a missing or incorrect username, update the customer's NDSP username before retrying.