# Conditional Webhooks


![image.png](https://api.apidog.com/api/v1/projects/451700/resources/377073/image-preview)


Webhooks provide a streamlined approach to facilitate communication between applications, offering the advantage of receiving notifications whenever an app receives data from another app. They play a critical role in establishing an event-based communication channel, connecting application owners with Salla. The primary purpose of webhooks is to ensure the synchronization of data between two separate applications.

Webhooks form the foundation of the infrastructure that supports numerous online activities. By [subscribing to a webhook](https://docs.salla.dev/doc-421119#list-of-salla-store-events), developers anticipate receiving a payload that contains relevant information pertaining to the events they are interested in. However, dealing with large volumes of content within these payloads can sometimes be overwhelming and challenging to navigate. This is where Salla Rules comes into play.

Salla Rules offers developers the ability to exercise control and customization over [webhooks](https://docs.salla.dev/doc-421119), utilizing the supported [attributes](https://docs.salla.dev/doc-421120#attributes). Rules enable the breakdown of simple business rules into smaller specification objects, which can later be combined to express more complex rules. This modular approach allows you as a developer to tailor their webhook experiences according to their specific needs and requirements.


## Importance of Rules

### Webhooks Targeting

Narrowing down the received payload is an achievable goal, as rules introduce you to conditional webhooks. Your communication now turns out to be an event-based communication with Salla, and the same is applied in the received payload.

Salla has provided the configurability feature to webhooks. In a sense, Rules contain basic filtering, which allow writing conditions and then afterwards receive particular payload based on the written condition.

As your business grows, you will need to redouble on your service quality served, accuracy delievred, and effort done. With rules, you can easily reduce the amount of the events you listen to, as they usually come loaded in payloads. That said, you only recieve the payloads you are in need in your app.

With rules, you get to head directly to take actions as decisions are easily made, and that means no more time wasted on time-consuming processes. Check for an [overview of webhooks](https://docs.salla.dev/doc-421119) on Salla docs for more details.

<!-- ### Helps Businesses -->

<!-- Business rules can be written as text using a dedicated language, very close to SQL. We refer to them as rules or they can be encapsulated in single classes and referred to as specifications.

Once a rule (or a specification) is written, it can check if a single candidate satisfies it or directly query a data source.

You get to express business rules in a dedicated, simple language. Then, these business rules can be encapsulated in specification classes, reused, and composed to form more complex rules.

Specifications are now reusable and testable. And last but not least, these rules can be used both to check if a candidate satisfies it and to filter any data source. -->

## Use Cases

The following are some use cases that webhooks can be used for:

- You can use rules in webhooks to filter updated carts that contain specific coupon codes.
- You can use rules in webhooks to uniquely identify specific order from a list of orders.
- You can also use rules in webhooks to recognize a specific product using its attributes (SKU, name, etc.).

<!-- Recieve bulk data -->
<!-- Recieve bulk data of Abandoned carts -->
<!-- Create copun codes based on a product with abandanoneded carts -->

<!--

In general, webhooks are crucial for establishing an event-based communication channel between your application and the application architecture of your service provider. They keep critical data synchronized between two distant apps.

As a result, webhooks serve as the foundation for the infrastructure that underpins many of the online activities we take for granted. Consider payment notifications.

If an e-commerce retailer utilizes a third-party payment gateway, the 'payment' event occurs outside of the merchant's website. The payment gateway will use webhooks to call the retailer's registration API and send payment data as soon as it is available. The retailer’s server then accepts this data, enabling it to update its database and user-facing screens.

--- -->

## General Standards in Attributes

Some Binary, Relational, and Logical operators are used when writing rules for a Salla webhook, such as equality, bitwise, and more.

Following the general standards is a must to obtain successful responses, so make sure to follow them. These rules act like conditional webhooks, for you to receive specific data.

Operations, expressions, and conditions to your webhook can be written. For instance, you may use `=,!=,AND,OR` etc in such a manner: `payment_method = YOUR_PAYMENT_METHOD` or in combination `payment_method = mada OR price < 50`. That adds more capability to filter the response based on conditionalities. In the following section, you can look up more into how you can construct your own rules using real-world examples.

## Write Your First Rule

<!-- First, regsiter your webhook using the [Register Webhook](api-5394134) endpoint .

Request

```json
{
  "name": "Salla Update Customer Event",
  "event": "customer.updated",
  "url": "https://webhook.site/07254470-c763-4ee3-bef1-ab2480262814",
  "headers": [
    {
      "key": "Authorization",
      "value": "Your Secret token"
    },
    {
      "key": "Accept-Language",
      "value": "AR"
    }
  ]
}
```

The above `payload` is the normal webhook registration in `Salla`, which will send data from Salla to your server when ever `Customer profile has updated`. Now let's add some rules -->

The following payload registers a new webhook on the [Merchant's dashboard](https://s.salla.sa), not on the [Partners Portal](https://portal.salla.partners), where the developer will be notified whenever the Merchant [created an order](https://docs.salla.dev/doc-421119#order).

```json
{
  "name": "Salla Order Created Event",
  "event": "order.created",
  "url": "https://webhook.site/a61ca376-dd98-4053-b2c4-8ba9cca470fc",
  "version": 2,
  "rule": "total > 100",
  "headers": [
    {
      "key": "Authorization",
      "value": "Your Secret token"
    },
    {
      "key": "Accept-Language",
      "value": "AR"
    }
  ]
}
```
<!-- 
In the above payload you will notice two new field the `version` and `rule` that only exist in [Salla V2's API](https://docs.salla.dev/docs/merchent/openapi.json/paths/~1webhooks~1subscribe/post):

- The **version** tell us what API version you are using; currently it **Salla V2**.

- The **rule** is where you put your custom logic for the webhook by binding to what is supported in the [attributes section](https://docs.salla.dev/docs/merchent/ZG9jOjI0NTE3NDgz-conditional-webhooks#attributes). -->

<!--
!!! note

    Rules only work on Salla V2! -->

<!-- In the rule field we added `branch_id = '827301`, this tells Salla that you want to trigger your webhook whenever a an order is created from a specific `branch` that is of ID `827301`. -->

That said, you have successfully set your first webhook with rules. The next section will be rules to apply in other webhooks' events.

### Examples

The following two examples showcase how conditional webhooks can be implemented practically in your webhook rules queries.

<Tabs>
  <Tab title="Special Offer Webhook Request">

```json
{
  "name": "Salla Special Offer Created Event",
  "event": "specialoffer.created",
  "url": "https://webhook.site/a61ca376-dd98-4053-b2c4-8ba9cca470fc",
  "version": 2,
  "rule": "status = `active` OR applied_to = `first_order`",
  "headers": [
    {
      "key": "Authorization",
      "value": "Your Secret token"
    },
    {
      "key": "Accept-Language",
      "value": "AR"
    }
  ]
}
```

In the above example the webhook was set the event to `specialoffer.created`. In the rule section, we added `OR`
that means, when one of the conditions are `true`, this wil trigger the webhook. In our example, the webhook will be triggered whenever there is a `status` equaling to `active`, or the the special offer created is applied to `order`.

  </Tab>
  <Tab title="Customer Webhook Request">
      
```json
{
  "name": "Salla Update Customer Event",
  "event": "customer.created",
  "url": "https://webhook.site/a61ca376-dd98-4053-b2c4-8ba9cca470fc",
  "version": 2,
  "rule": "city	 = `الرياض` AND location != `حي اليرموك`",
  "headers": [
    {
      "key": "Authorization",
      "value": "Your Secret token"
    },
    {
      "key": "Accept-Language",
      "value": "AR"
    }
  ]
}
```

In the above example, the webhook will be triggered whenever a customer has been created. In the rule section, we added `And`;
that means that both conditions should be `true` to trigger the webhook. In our example, the webhook will be triggered whenever the city is `الرياض` and location is not the whereabouts of `حي اليرموك`.
      
  </Tab>

</Tabs>






<!-- #### Category

Request

```json
{
  "name": "Salla Update Category Event",
  "event": "category.updated",
  "url": "https://webhook.site/a61ca376-dd98-4053-b2c4-8ba9cca470fc",
  "version": 2,
  "rule": "status == active And sort_order >= 2",
  "headers": [
    {
      "key": "Authorization",
      "value": "Your Secret token"
    },
    {
      "key": "Accept-Language",
      "value": "AR"
    }
  ]
}
```

In the above example, the webhook will be triggered whenever a category has been updated. In the rule section, we added `And`;
that means that both conditions should be `true` to trigger the webhook. In our example, the webhook will be triggered whenever a status is `active` and `sort_order` is greater than or equal to `2`. -->
<!--
#### Product

Request

```json
{
  "name": "Salla Update Product Event",
  "event": "product.created",
  "url": "https://webhook.site/a61ca376-dd98-4053-b2c4-8ba9cca470fc",
  "version": 2,
  "rule": "status = hidden AND unlimited_quantity = true OR is_available = true",
  "headers": [
    {
      "key": "Authorization",
      "value": "Your Secret token"
    },
    {
      "key": "Accept-Language",
      "value": "AR"
    }
  ]
}
```

In the above example, the webhook will be triggered whenever a product has been created. In the rule section, we added `And`, `OR`;
that means that whenever both `status` and `unlimited_quantity` are true, then the webhook will be triggered or if `is_available` is `true` then the webhook will triggered.

!!! note
Easily, you can customize your business logic as you want. -->

## Attributes

The following attributes allow you to write conditions only based on them. For example, if you want to write conditions for the `Category` event, use in the `rule` section one or more of the following:

|            |
| ---------- |
| `id`         |
| `name`       |
| `parent_id`  |
| `status`     |
| `sort_order` |


And the same logic goes for all the supported attributes:
- [Order](#order)
- [Product](#product)
- [Customer](#customer)
- [Special Offers](#special-offers)
- [Category](#category)
- [Brand](#brand)
- [Cart](#cart)
- [Miscellaneous](#miscellaneous)
### [Order](https://docs.salla.dev/doc-421119#order)


<Tabs>
  <Tab title="Events">

The supported events are the following:

| Event Name                        |
| --------------------------------- |
| `order.created `                  |
| `order.updated `                  |
| `order.status.updated `           |
| `order.cancelled `                |
| `order.refunded `                 |
| `order.deleted `                  |
| `order.products.updated `         |
| `order.payment.updated `          |
| `order.coupon.updated `           |
| `order.total.price.updated `      |
| `order.shipment.creating `        |
| `order.shipment.created `         |
| `order.shipment.cancelled `       |
| `order.shipment.return.creating ` |
| `order.shipment.return.created `  |
| `order.shipment.return.cancelled` |
| `order.shipping.address.updated ` |

  </Tab>
  <Tab title="Properties">

The rules can contain on or more of the following attributes:

| Name                                        | type          |
| ------------------------------------------- | ------------- |
| `id `                                       | Integer       |
| `reference_id `                             | Integer       |
| `date `                                     | Date and Time |
| `customer_id `                              | Integer       |
| `status_id `                                | Integer       |
| `branch_id `                                | Integer       |
| `coupon_code `                              | String        |
| `feedback_status `                          | String        |
| `total `                                    | Float         |
| `total_discount `                           | Float         |
| `sub_total `                                | Float         |
| `shipping_cost `                            | Float         |
| `cash_on_delivery `                         | Float         |
| `tax_percent `                              | String        |
| `tax_amount `                               | Float         |
| `currency `                                 | String        |
| `payment_method `                           | String        |
| `payment_bank_id `                          | Integer       |
| `shipment_id `                              | Integer       |
| `shipment_pickup_id `                       | Integer       |
| `shipment_tracking_link `                   | String        |
| `shipment_company_id `                      | Integer       |
| `shipment_company_name `                    | String        |
| `shipment_receiver_name `                   | String        |
| `shipment_receiver_email `                  | String        |
| `shipment_receiver_phone `                  | String        |
| `shipment_shipper_name `                    | String        |
| `shipment_shipper_company_name `            | String        |
| `shipment_shipper_email `                   | String        |
| `shipment_shipper_phone `                   | String        |
| `shipment_pickup_address_country `          | String        |
| `shipment_pickup_address_city `             | String        |
| `shipment_pickup_address_shipping_address ` | String        |
| `shipment_pickup_address_street_number `    | String        |
| `shipment_pickup_address_block `            | String        |
| `shipment_pickup_address_postal_code `      | String        |
| `shipment_pickup_address_geo_lat `          | String        |
| `shipment_pickup_address_geo_lng `          | String        |
| `shipment_dropoff_address_country `         | String        |
| `shipment_dropoff_address_city `            | String        |
| `shipment_dropoff_address_shipping_address` | String        |
| `shipment_dropoff_address_street_number `   | String        |
| `shipment_dropoff_address_block `           | String        |
| `shipment_dropoff_address_postal_code `     | String        |
| `shipment_dropoff_address_geo_lat `         | Float         |
| `shipment_dropoff_address_geo_lng `         | Float         |


  </Tab>

</Tabs>


### [Product](https://docs.salla.dev/doc-421119#product)


<Tabs>
  <Tab title="Events">

The supported events are the following:

| Event Name             |
| ---------------------- |
| `product.created `     |
| `product.updated `     |
| `product.deleted `     |
| `product.available `   |
| `product.quantity.low` |

  </Tab>
  <Tab title="Properties">
      
The rules can contain on or more of the following attributes:

| Name                  | type              |
| --------------------- | ----------------- |
| `id `                 | Integer           |
| `currency `           | String            |
| `promotion_title `    | String            |
| `promotion_sub_title` | String            |
| `sku `                | String            |
| `type `               | String            |
| `name `               | String            |
| `short_link_code `    | String            |
| `price `              | Float             |
| `description `        | String            |
| `quantity `           | Integer           |
| `status `             | String            |
| `is_available `       | boolean           |
| `sale_price `         | Float             |
| `sale_end `           | Integer or String |
| `require_shipping `   | boolean           |
| `cost_price `         | Float             |
| `weight `             | Float             |
| `with_tax `           | boolean           |
| `included_tax `       | boolean           |
| `url `                | String            |
| `has_special_price `  | boolean           |
| `regular_price `      | Float             |
| `max_items_per_user ` | Integer           |
| `show_in_app `        | boolean           |
| `notify_quantity `    | Integer or String |
| `unlimited_quantity ` | boolean           |
| `managed_by_branches` | boolean           |
| `brand_id `           | Integer           |

  </Tab>
</Tabs>



### [Customer](https://docs.salla.dev/doc-421119#customer)


<Tabs>
  <Tab title="Events">

The supported events are the following:

| Event Name             |
| ---------------------- |
| `customer.created `    |
| `customer.updated `    |
| `customer.login `      |
| `customer.otp.request` |
      
  </Tab>
  <Tab title="Properties">
    
The rules can contain on or more of the following attributes:

| Name          | type          |
| ------------- | ------------- |
| `id `         | Integer       |
| `first_name ` | String        |
| `last_name `  | String        |
| `mobile `     | String        |
| `mobile_code` | String        |
| `email `      | String        |
| `avatar `     | String        |
| `gender `     | String        |
| `birthday `   | Date and Time |
| `city `       | String        |
| `country `    | String        |
| `currency `   | String        |
| `location `   | String        |


  </Tab>

</Tabs>



### [Special Offers](https://docs.salla.dev/doc-421119#special-offer)


<Tabs>
  <Tab title="Events">
      
The supported events are the following:

| Event Name             |
| ---------------------- |
| `specialoffer.created` |
| `specialoffer.updated` |

      
  </Tab>
  <Tab title="Properties">

The rules can contain on or more of the following attributes:

| Name          | type          |
| ------------- | ------------- |
| `id `         | Integer       |
| `name `       | String        |
| `message `    | String        |
| `offer_type ` | String        |
| `status `     | String        |
| `expiry_date` | Date and Time |


  </Tab>

</Tabs>


### [Category](https://docs.salla.dev/doc-421119#category)



<Tabs>
  <Tab title="Events">
      
The supported events are the following:

| Event Name         |
| ------------------ |
| `category.created` |
| `category.updated` |
  </Tab>
  <Tab title="Properties">

The rules can contain on or more of the following attributes:

| Name         | type    |
| ------------ | ------- |
| `id `        | Integer |
| `name `      | String  |
| `parent_id ` | Integer |
| `status `    | String  |
| `sort_order` | Integer |


  </Tab>

</Tabs>


### [Brand](https://docs.salla.dev/doc-421119#brand)


<Tabs>
  <Tab title="Events">
      
The supported events are the following:

| Event Name      |
| --------------- |
| `brand.created` |
| `brand.updated` |
| `brand.deleted` |

  </Tab>
  <Tab title="Properties">

The rules can contain on or more of the following attributes:

| Name         | type    |
| ------------ | ------- |
| `id `        | Integer |
| `name `      | String  |
| `status `    | boolean |
| `custom_url` | String  |
  </Tab>
 
</Tabs>

### [Cart](https://docs.salla.dev/doc-421119#cart)

<Tabs>
  <Tab title="Events">

The supported event is the following:

| Event Name        |
| ----------------- |
| `abandoned.cart ` |

  </Tab>
  <Tab title="Properties">

The rules can contain on or more of the following attributes:

| Name               | type          |
| ------------------ | ------------- |
| `id `              | Integer       |
| `subtotal `        | Float         |
| `currency `        | String        |
| `total `           | Float         |
| `coupon_code `     | String        |
| `customer_id `     | Integer       |
| `customer_avatar ` | String        |
| `customer_name `   | String        |
| `customer_mobile ` | String        |
| `created_at `      | Date and Time |
| `updated_at `      | Date and Time |



  </Tab>

</Tabs>



### [Miscellaneous](https://docs.salla.dev/doc-421119#miscellaneous)

<Tabs>
  <Tab title="Events">
The supported event is the following:

| Event Name     |
| -------------- |
| `review.added` |
  </Tab>
  <Tab title="Properties">

The rules can contain on or more of the following attributes:

| Name           | type    |
| -------------- | ------- |
| `parent_id `   | Integer |
| `store_id `    | Integer |
| `customer_id ` | Integer |
| `product_id `  | Integer |
| `page_id `     | Integer |
| `order_id `    | Integer |
| `rating `      | Integer |
| `content `     | String  |
| `status `      | String  |
| `ip_address `  | String  |
| `ip_city `     | String  |
| `ip_country `  | String  |
| `type `        | String  |

  </Tab>
 
</Tabs>