webhooks-actions is used with Salla to simplify the communication between your App and Salla APIs.
Explore our blogs »
Report Bug · Request Feature · </Salla Developers>
Webhooks simplify the communication between your App and Salla APIs. In this way, you will be notified whenever your app receives payload/data from the Salla APIs. These webhooks are triggered along with many actions such as an order or product being created, a customer logs in, a coupon is applied, and much more.
This module helps you to listen for notifications from Salla APIs within your Nodejs applications and Express.js, By using it you can implement listeners for every event sent by Salla to your server.
For more information about Salla's Webhooks implementation, check our Webhooks Explained.
$ npm install @salla.sa/webhooks-actions
With Salla Webhooks Actions you can listen for notifications sent by Salla to your endpoint set by Express.js or other frameworks like next.js
You you can add listeners as a function, it will be executed every time an event is received.
// Import Deps
const express = require("express");
const bodyParser = require("body-parser");
const consolidate = require("consolidate");
// Salla Webhook API
const SallaWebhook = require("@salla.sa/webhooks-actions");
// initialize app
const port = 8081;
let eventsStack = [];
const app = express();
app.use(bodyParser.urlencoded({ extended: false }));
app.use(bodyParser.json());
require("dotenv").config();
/*
A .env file should be automatically created in the root directory of your project when creating your project with @salla/SallaCLI.
environment-specific variables on new lines in the form of NAME=VALUE. For example:
SALLA_OAUTH_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SALLA_OAUTH_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SALLA_WEBHOOK_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SALLA_AUTHORIZATION_MODE=easy
SALLA_OAUTH_CLIENT_REDIRECT_URI=https://example.com/oauth/callback
SALLA_APP_ID=123456789
...
*/
const SALLA_WEBHOOK_SECRET = process.env.SALLA_WEBHOOK_SECRET;
SallaWebhook.setSecret(SALLA_WEBHOOK_SECRET);
// Add Webhook listeners
SallaWebhook.on("app.installed", (eventBody, userArgs) => {
// handel app.installed event
});
SallaWebhook.on("app.stroe.authorize", (eventBody, userArgs) => {
// handel app.app.stroe.authorize event
});
// POST /webhook
app.post("/webhook", function (req, res) {
SallaWebhook.checkActions(req.body, req.headers.authorization, {
/* your args to pass to action files or listeners */
});
});
app.listen(port, function () {
console.log("App is listening on port " + port);
});You you can add listeners as files easily using the salla app create-webhook app.updated command; the file will be executed every time an event is received .
/*
Actions
├───app
│ installed.js
│ store.authorize.js
├───brand
│ created.js
├───customer
│ login.js
│ otp.created.js
│ request.js
│ updated.js
├───order
│ created.js
├───project
│ created.js
└───store
branch.created.js
*/
// Import Deps
const express = require("express");
const bodyParser = require("body-parser");
const consolidate = require("consolidate");
// Salla Actions API
const SallaWebhook = require("@salla.sa/webhooks-actions");
// initialize app
const port = 8081;
let eventsStack = [];
const app = express();
app.use(bodyParser.urlencoded({ extended: false }));
app.use(bodyParser.json());
require("dotenv").config();
/*
A .env file should be automatically created in the root directory of your project when creating your project with @salla/SallaCLI.
environment-specific variables on new lines in the form of NAME=VALUE. For example:
SALLA_OAUTH_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SALLA_OAUTH_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SALLA_WEBHOOK_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SALLA_AUTHORIZATION_MODE=easy
SALLA_OAUTH_CLIENT_REDIRECT_URI=https://example.com/oauth/callback
SALLA_APP_ID=123456789
...
*/
const SALLA_WEBHOOK_SECRET = process.env.SALLA_WEBHOOK_SECRET;
SallaWebhook.setSecret(SALLA_WEBHOOK_SECRET);
SallaWebhook.on("all", (eventBody, userArgs) => {
// handel all actions even thats not authorized . good for logging .
});
// the endpoint to receive actions from Salla
app.post("/webhooks", (req, res) =>
SallaWebhook.checkActions(
req.body,
req.headers.authorization,
...{
/* add more arguments, will be passed to listener functions and SallaWebhook js files*/
}
)
);
app.listen(port, function () {
console.log("App is listening on port " + port);
});Salla already defined a list of the webhooks/actions that are triggered automatically. The predefined webhooks/actions can be found in the folder Actions.
| Action Name | Description |
|---|---|
| order.created | This indicates a singular order has been created |
| order.updated | Details, data and/or content of a specific order have been refreshed updated |
| order.status.updated | Whenever there is an order status update, this is triggered |
| order.cancelled | This happens when an order is cancelled |
| order.refunded | The refund action to refund the whole order is triggered. |
| order.deleted | This indicates an order has been deleted |
| order.products.updated | Order products is updated |
| order.payment.updated | A payment method has been updated |
| order.coupon.updated | This is triggered whenever a Coupon is updated |
| order.total.price.updated | A total price of an order has been updated |
| order.shipment.creating | This indicates a new shipment is being created |
| order.shipment.created | This indicates a new shipment has been created |
| order.shipment.cancelled | This indicates a an order shipment has been cancelled |
| order.shipment.return.creating | This is triggered when a returned order shipment is being created |
| order.shipment.return.created | This is triggered when a returned order shipment has been created |
| order.shipment.return.cancelled | This is triggered when a returned order shipment has been cancelled |
| order.shipping.address.updated | Occurs when an Order shipping address is updated |
| Action Name | Description |
|---|---|
| product.created | A new product is created. Payload of the new product are to accompanying the product |
| product.updated | Add/Modify details of a product |
| product.deleted | Delete a product along with all its variants and images |
| product.available | Flags a product as stock available |
| product.quantity.low | Shows warnings whenever a stock is of low quantity |
| Action Name | Description |
|---|---|
| shipping.zone.created | This is triggered when a shipping zone has been created for a custom shipping company |
| shipping.zone.updated | This is triggered when a shipping zone has been updated for a custom shipping company |
| shipping.company.created | This is triggered when a custom shipping company has been created |
| shipping.company.updated | This is triggered when a custom shipping company has been updated |
| shipping.company.deleted | This is triggered when a custom shipping company has been deleted |
| Action Name | Description |
|---|---|
| customer.created | Create a new customer record |
| customer.updated | Update details for a customer |
| customer.login | Triggered whenever a customer log in |
| customer.otp.request | One-Time Password request for a customer |
| Action Name | Description |
|---|---|
| category.created | Creates a new category for products to be put under |
| category.updated | Add new or reform existing category details |
| Action Name | Description |
|---|---|
| brand.created | Creates a new Brand. |
| brand.updated | Triggered when Information about a specific Brand is updated/refurbished/streamlined |
| brand.deleted | An existing brand is then deleted and removed from a store |
| Action Name | Description |
|---|---|
| store.branch.created | Creates a new store. |
| store.branch.updated | Updates an existing branch |
| store.branch.setDefault | Sets for default a specific branch |
| store.branch.activated | Activates a disabled branch |
| store.branch.deleted | Deletes a branch |
| storetax.created | Creates a new Store Tax |
| Action Name | Description |
|---|---|
| abandoned.cart | Outputs a list of abandoned carts |
| coupon.applied | Creates a discount code in the form of a coupon |
| Action Name | Description |
|---|---|
| specialoffer.created | Creates a new special offer |
| specialoffer.updated | Updates a special offer |
| Action Name | Description |
|---|---|
| review.added | A product review has been added |
$ npm install --dev
$ npm test
The team is always here to help you. Happen to face an issue? Want to report a bug? You can submit one here on Github using the Issue Tracker. If you still have any questions, please contact us via the Telegram Bot or join in the Global Developer Community on Telegram.
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
If you discover any securitys-related issues, please email security@salla.sa instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.