Skip to content
Crossmart Docs

Add a webhook endpoint. Its signing secret is returned once.

POST
/api/v1/workspaces/{workspaceId}/webhook-endpoints
curl --request POST \
  --url https://api.crossmart.io/api/v1/workspaces/example/webhook-endpoints \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "url": "https://example.com/crossmart/webhooks", "description": "example", "eventTypes": [ "order.created" ] }'

Events are POSTed to the URL as JSON, signed in the Crossmart-Signature header.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
workspaceId
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
url
required

Where events are POSTed. https and a public address; plain http only outside production.

string

Example 

https://example.com/crossmart/webhooks
description
string
nullable <= 500 characters
eventTypes
required

The events to receive. webhook.test cannot be subscribed to.

Array<string>
Allowed values: order.created order.updated inventory.stock_changed listing.published listing.failed listing.removed product.created product.updated product.deleted webhook.test

Responses

Section titled “Responses”

201

Section titled “201”
Media typeapplication/json
object
endpoint
required
object
id
required
string format: uuid
url
required
string
description
required
string
nullable
eventTypes
required
Array<string>
Allowed values: order.created order.updated inventory.stock_changed listing.published listing.failed listing.removed product.created product.updated product.deleted webhook.test
enabled
required

False when turned off by someone or after repeated failures

boolean
disabledReason
required

MANUAL: turned off by someone. FAILING: turned off by Crossmart.

string
Allowed values: MANUAL FAILING
disabledAt
required
string format: date-time
nullable
consecutiveFailures
required

Failed attempts since the last delivery that went through

number
lastDelivery
required

The latest delivery attempt, whatever event it carried; null before the first

object
attemptedAt
required
string format: date-time
outcome
required

SUCCEEDED: the endpoint answered 2xx. FAILED: anything else, or no answer.

string
Allowed values: SUCCEEDED FAILED
responseStatus
required

Null when no response came: a timeout or a connection error

number
nullable
error
required

Why the attempt failed; null on success

string
nullable
previousSecretExpiresAt
required

Until then deliveries are also signed with the secret the last rotation replaced

string format: date-time
nullable
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
secret
required

The signing secret. Shown once; store it now.

string

Example 

{
  "endpoint": {
    "url": "https://example.com/crossmart/webhooks",
    "description": "Order notifications to n8n",
    "eventTypes": [
      "order.created"
    ],
    "disabledReason": "MANUAL",
    "lastDelivery": {
      "outcome": "SUCCEEDED",
      "responseStatus": 200,
      "error": "The endpoint answered with HTTP 503"
    }
  },
  "secret": "whsec_3q2-7wEXAMPLEsecretVALUE0123456789abcdef"
}

400

Section titled “400”

The URL is not https (in production), or not a public address

402

Section titled “402”

The organization’s plan does not allow this (ENTITLEMENTS_ENFORCED is on). code and feature say why; upgrading the plan resolves it.

Media typeapplication/json
object
statusCode
required
number
error
required
string
code
required
string
Allowed values: plan_limit_reached plan_feature_not_included
message
required
string
feature
required
string
Allowed values: active_listings channel_connections workspaces members api_keys webhook_endpoints ai_credits autonomous_agents bring_your_own_key
plan
required

The code of the organization’s plan

string
limit
required

Null is unlimited

number
nullable
usage
required
number
requested
required

How many more the request asked for

number

Example 

{
  "statusCode": 402,
  "error": "Payment Required",
  "code": "plan_limit_reached",
  "message": "The Free plan includes 2 connected channels, and 2 are in use. Upgrade the plan to add more.",
  "feature": "active_listings",
  "plan": "free"
}

503

Section titled “503”

The server has no CREDENTIALS_MASTER_KEY to encrypt secrets with