Webhooks
Placeholders
Placeholders allow you to customize webhook URLs and payloads with dynamic values. When a webhook is triggered, placeholders are replaced with actual data from the event.
Placeholder Syntax
Placeholders use double curly braces:
{{placeholderName}}
Example webhook body:
{
"event": "{{entity}}.{{action}}",
"id": "{{id}}",
"environment": "{{environment}}"
}
Becomes (when triggered):
{
"event": "Product.update",
"id": "12345",
"environment": "prod"
}
Always Available Placeholders
These placeholders are available for all webhook entities:
| Placeholder | Description | Example Value |
|---|---|---|
{{entity}} | Entity type that triggered the webhook | Product, Order, Customer |
{{action}} | Action performed | create, update, delete |
{{account}} | Your webshop/account name | mystore |
{{environment}} | Environment where action occurred | prod, dev, qa |
{{id}} | ID(s) of affected entity | 12345 or 12345,12346,12347 |
ID Placeholder Details
The {{id}} placeholder can contain:
- Single ID - When one entity is affected:
12345 - Comma-separated IDs - When multiple entities are affected:
12345,12346,12347
When bulk operations affect multiple entities, all IDs are included in the placeholder. Parse comma-separated values in your webhook handler.
Partially Available Placeholders
These placeholders are available only for specific entities or actions:
| Placeholder | Available For | Description | Example Value |
|---|---|---|---|
{{paymentName}} | Capture, Refund | Payment method name | Credit Card, PayPal |
{{channelName}} | Capture, Refund, ProductMonitor, Customer (password reset) | Channel/website name | Main Store |
{{channelUrl}} | Customer (password reset) | Channel/website URL | https://mystore.com |
{{resetKey}} | Customer (password reset) | Password reset key | abc123xyz789 |
{{orderRowId}} | Order (cancelrow action) | Specific order row ID | 67890 |
{{returnId}} | Order (return action) | Return ID | 54321 |
{{subEntity}} | Product, Order | What specifically changed (see below) | price, stockBalance |
SubEntity Placeholder
The {{subEntity}} placeholder provides granular change tracking for Product and Order entities. It tells you exactly what changed without needing to fetch the full entity.
When SubEntity is Empty
If the entire entity was updated (e.g., full product import), {{subEntity}} will be empty. This indicates a comprehensive change rather than a specific field update.
Product SubEntity Values
| Value | Description | Example Use Case |
|---|---|---|
stockBalance | Stock quantity changed | Trigger restock notification, update inventory dashboard |
price | Product price updated | Update price comparison feeds, notify customers on watchlist |
image | Product image added/modified/deleted | Refresh product image cache, update CDN |
sortOrder | Sort order changed | Reindex product listings |
purchasePrice | Purchase price updated | Update margin calculations |
variant | Variant information changed | Sync variant options to marketplace |
parameter | Product parameter added/modified/deleted | Update product specifications on external sites |
category | Category assignment changed | Update category navigation, refresh sitemaps |
relation | Related products changed | Update "frequently bought together" widgets |
item | Product item (SKU) changed | Sync SKU data to ERP system |
Example: Track only price changes
// Webhook body
{
"event": "{{entity}}.{{action}}",
"productId": "{{id}}",
"changeType": "{{subEntity}}",
"environment": "{{environment}}"
}
// When price changes
{
"event": "Product.update",
"productId": "12345",
"changeType": "price",
"environment": "prod"
}
Order SubEntity Values
| Value | Description | Example Use Case |
|---|---|---|
row | Order row (line item) changed | Update fulfillment system when items added/removed |
status | Order status changed | Send customer notification for status updates |
ProductMonitor Placeholders
When entity is ProductMonitor, these additional placeholders are available:
| Placeholder | Description | Example Value |
|---|---|---|
{{email}} | Customer email address | customer@example.com |
{{language}} | Language code | en-US, sv-SE |
{{productId}} | Monitored product ID | 12345 |
{{productName}} | Product name | Blue Widget |
{{productUrl}} | Product page URL | https://mystore.com/products/blue-widget |
{{productPrice}} | Current product price | 299.00 |
{{productImage}} | Product image URL | https://cdn.mystore.com/images/blue-widget.jpg |
{{itemId}} | Specific item/SKU ID | 12345-M-BLUE |
{{itemName}} | Item/SKU name | Blue Widget - Medium |
If a placeholder is not available for the current entity/action combination, it will be left unchanged in the output (e.g.,
{{unavailablePlaceholder}}). Handle unreplaced placeholders in your webhook handler.