Webhooks

What is a webhook?

A webhook lets push order-event notifications to your system in near real time. When a supported order event occurs, sends an HTTP POST request to your configured webhook URL.

Webhook Setup

Webhook configuration is handled in the Admin Panel. Please contact your account manager to set up or update your webhook details.

What you need to configure

After your account has been registered with , you can provide details to set up your webhook and receive notifications listed in Notifications.

Field	Required	Description
Webhook URL	Yes	The webhook endpoint that receives POST requests.
Authentication Type	Yes	One of the supported auth types listed below.
Authentication Details	Depends on auth type	Credentials/details required by the selected auth type.
Headers	Optional	Additional static headers to include in webhook calls (up to 3 headers in the current admin UI).
Transformer	Optional	Notification mapping/shape customization for your integration.

Webhook request format

Webhook notifications follow the CloudEvents-style envelope used by .

Property	Description
cloudEventsVersion	CloudEvents version for the payload envelope.
eventType	Event name, such as com.example.OrderConfirmed.
eventTypeVersion	Version of the event type contract.
source	Source URI for the order/event.
eventID	Unique event identifier. Use this for idempotency.
eventTime	Event creation timestamp.
contentType	Payload content type (typically application/json).
data	Event-specific payload body.

Example payload references:

• CloudEvents envelope details
• Order Confirmed payload example
• Order Item Shipped payload example
• All supported notifications

Supported authentication types

Use one of the following auth type values when configuring webhook integration:

Auth Type Value	UI Label	What to provide
NoAuth	No Auth (Open Endpoint)	No auth fields required.
BasicAuth	Basic Auth (Username and Password)	authUrl, username, password
BearerAuth	Bearer Auth (Client ID and Secret)	authUrl, clientId, secret
ApikeyAuth	API Key (API key to be passed in header)	key, value

How each type behaves

NoAuth

• sends webhook notifications directly to your webhook URL.
• No authentication handshake is performed.

ApikeyAuth

• A header is added to the webhook call using your configured key and value.
• Example: if key = x-api-key and value = abc123, the webhook request includes x-api-key: abc123.

BasicAuth

• Before sending the webhook event, calls your configured authUrl with Basic Auth (username + password).
• The auth response is used by your integration mapping to authorize the final webhook call.

BearerAuth

• Before sending the webhook event, calls your configured authUrl with clientId and secret.
• The returned token/credentials are used by your integration mapping to authorize the final webhook call.

Delivery expectations

Your webhook endpoint should:

1. Accept HTTP POST with JSON body.
2. Return a 2xx response quickly after basic validation.
3. Complete auth and webhook responses within 20 seconds to avoid timeout failures.

If your endpoint returns non-2xx, is unreachable, or times out, the notification delivery is treated as failed.

Go-live checklist

• Webhook URL is HTTPS and publicly reachable.
• An auth type has been selected.
• Any required custom headers are configured.
• Endpoint returns 2xx for valid events sent by spacefolder