Salla conditional webhooks: filter events before they reach your app

An ecommerce app rarely needs every event a store can emit. A fulfillment integration may care about orders above a certain value; a promotion workflow may act only on carts carrying a particular coupon; an inventory service may listen for a limited set of product changes. Receiving everything and discarding most of it inside your server wastes ingress, queue and worker capacity—and makes the useful signals harder to operate.

Salla's conditional webhook documentation exposes a `rule` on a webhook subscription so the platform can evaluate supported conditions before delivering an event. The feature is not a new launch: the documentation was verified on 26 September 2026 and is presented here as a practical integration pattern, not as breaking news.

What a conditional webhook changes

A normal webhook subscription chooses an event, such as `order.created` or `product.quantity.low`. A conditional subscription adds a predicate over attributes supported for that event family. Salla documents relational and logical operators including `=`, `!=`, `AND` and `OR`, and gives `total > 100` as a registration example. It also lists supported families covering orders, products, customers, special offers, categories, brands, abandoned carts and reviews.

The filter runs before delivery. If an event does not match, your endpoint does not receive that payload. This is useful when the business action genuinely applies to a stable subset: route only high-value orders to a manual review queue, react only to selected promotion conditions, or trigger a specialized catalog workflow for defined products.

Filtering is not payload projection. A rule controls whether the webhook is delivered; it does not promise to remove unused fields from a matching payload. Apply data minimization and retention rules inside the app as well. And only use attributes documented for the exact event family—do not assume that a field visible in one order payload is legal in a product or cart rule.

Registering a rule through the Merchant API

The current Register Webhook endpoint is `POST /admin/v2/webhooks/subscribe`, requires the `webhooks.read_write` scope and defaults new subscriptions to webhook version 2. The URL must accept `POST`. A minimal request can look like this:

{
  "name": "High-value order review",
  "event": "order.created",
  "url": "https://app.example.com/webhooks/salla/orders",
  "version": 2,
  "rule": "total > 100",
  "headers": [
    {"key": "Authorization", "value": "<per-app-secret>"}
  ]
}

Use the merchant-scoped OAuth token only to call Salla's registration API; do not place it in the callback URL. Store the returned webhook identifier and the normalized rule in your own configuration so an operator can see what is deployed. Salla also provides List Active Webhooks, which returns fields including the event, version, rule, URL and headers; use it to compare desired and actual configuration.

One contract detail deserves a deployment test: the registration documentation says a new subscription using the same URL updates or restores an existing webhook. Do not assume that repeatedly posting different events to one identical URL creates independent subscriptions. Verify the resulting active-webhook list in a demo store, and use stable, intentionally distinct callback paths when the integration needs separately managed subscriptions.

What rules do not replace

A condition reduces the number of deliveries; it does not make the deliveries exactly once. Salla's Core Development playbook still prescribes the same processing sequence: verify the sender, acknowledge quickly, queue the payload, process it outside the request and make processing idempotent.

That means the public handler should validate the signature against the raw body, validate the envelope, persist it to a durable inbox, return 2xx and let a worker act. Give each side effect—creating a shipment, issuing a coupon, notifying an ERP—its own idempotency key. A retry must converge on the same state, not repeat the financial or fulfillment action.

A rule also does not recover an event that was never delivered or a condition that was wrong. The source of truth remains the platform API. Keep scheduled reconciliation for critical orders, inventory, payments and fulfillment. The detailed Salla and Zid webhook recovery guide covers the durable inbox, checkpoints and API backfill; conditional rules sit before that architecture, not instead of it.

Designing rules that remain understandable

Start from a business invariant, not from the expression syntax. “Only send orders above 100” is incomplete until the team defines currency handling, discounts, refunds and whether the threshold is based on the event's documented `total`. If the action is expensive or irreversible, re-read authoritative order state in the worker before acting.

Keep rules short. A rule with many `AND` and `OR` branches is hard to review and easy to misunderstand when precedence is unclear. Prefer several named subscriptions or a broader platform filter followed by explicit application policy when the decision changes often. The filter should remove obviously irrelevant traffic; the application should own business logic that needs versioning, feature flags, audit trails or rapid rollback.

Represent each subscription as configuration reviewed with code:

subscription: high_value_order_review_v1
event: order.created
rule: total > 100
owner: risk-operations
on_match: enqueue manual-review workflow
recovery: reconcile orders every 15 minutes

The `v1` is your configuration version, not Salla's webhook payload version. Store the old expression and change reason whenever the rule changes. This gives incident responders an answer to “which orders could have been filtered out during this interval?”

Safe rollout and change procedure

Build a fixture matrix from documented payload shapes: one event below the boundary, one equal to it, one above it, missing or nullable fields where the schema permits them, and combinations for every `AND` or `OR` branch. Unit-test your application policy, then trigger real store events in a Salla demo store to confirm what the platform actually delivers.

Before changing a production rule, record the current subscription returned by List Active Webhooks. Apply the new expression through the documented registration or update path, read the active configuration back, and run a canary business event. Watch the number of matching deliveries, signature failures, inbox writes, duplicate rate, worker lag and reconciliation drift.

Do not deploy a narrower rule and immediately delete your ability to reconstruct state. Keep overlapping API reconciliation long enough to compare the population selected by the rule with the authoritative records. If drift rises, roll back the rule and replay repairs through the same idempotent worker.

Cost and observability boundaries

Conditional delivery can reduce HTTP requests, raw-event storage, queue messages and worker executions. The saving depends on the selectivity of the rule and the cost of downstream work; there is no public benchmark that guarantees a percentage. Measure before and after using counts, not intuition.

Useful per-subscription metrics include expected source population, delivered events, rule-match rate, rejected signatures, acknowledgment latency, retries, inbox duplicates, processing failures and reconciliation repairs. The platform filter cannot report what your application never received, so source-population estimates must come from a bounded API query or another authoritative business count.

Avoid high-cardinality labels such as order IDs in metrics. Put identifiers in structured logs with retention controls, and aggregate metrics by merchant tier, event, rule version and outcome. This connects the integration to the broader practices in backend observability without turning customer data into monitoring labels.

The practical decision

Use Salla conditional webhooks when a stable, documented predicate can remove a large irrelevant portion of one event stream. They are especially useful before costly automations, AI calls or third-party integrations. Keep fast-changing or subtle business policy in your own code, where it can be tested, versioned and rolled back.

The reliable architecture has two distinct layers: Salla Rules chooses what reaches you, while your ingress and workers determine whether matching events are handled safely. Preserve signature verification, durable storage, queues, idempotency, reconciliation and observability even when the filter appears simple. That separation gives the merchant lower processing noise without trading away correctness.

Prepared by: Noor Yasser