@salla.sa/webhooks-actions

1.0.2 • Public • Published
Logo

Salla Webhooks Actions

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>

Overview

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 Expressjs, By using it you can impelement listernes for every event sent by Salla to your server .

For more information about Salla's Webhooks implementation, check our Webhooks Explained.

Webhooks Workflow

Webhooks Workflow

Installation

$ npm install @salla.sa/webhooks-actions

(back to top)

Usage

With Salla Webhooks Actions you can listen for notifications send by Salla to your endpoint set by Expressjs or other frameworks like next.js

Impelement Using Listeners

You you can add listeners as a function, it will be exeucted 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 createing 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.authoriz 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);
});

Impelement Using Folder Structure

You you can add listeners as files easly using the salla app create-webhook app.updated command; the file will be exeucted 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 createing 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 listner functions and SallaWebhook js files*/
    }
  )
);

app.listen(port, function () {
  console.log("App is listening on port " + port);
});

(back to top)

Salla already defined a list of the webhooks/actions that are triggered automatically. The predefined webhooks/actions can be found in the folder Actions.

Order Related Webhooks/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

(back to top)

Product Related Webhooks/Actions

** 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

(back to top)

Shipping Companies Related Webhooks/Actions

** 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

(back to top)

Customer Related Webhooks/Actions

** 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

(back to top)

Category Related Webhooks/Actions

** Action Name ** ** Description **
category.created Creates a new category for products to be put under
category.updated Add new or reform existing category details

(back to top)

Brand Related Webhooks/Actions

** Action Name ** ** Description **
brand.created Creates a new Brand.
brand.updated Triggered when Information about a sepcific Brand is updated/refurbished/streamlined
brand.deleted An existing brand is then deleted and removed from a store

(back to top)

Store Related Webhooks/Actions

** 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 Creats a new Store Tax

(back to top)

Cart Related Webhooks/Actions

** Action Name ** ** Description **
abandoned.cart Outputs a list of abandoned carts
coupon.applied Creates a discount code in the form of a coupon

(back to top)

Special Offer Related Webhooks/Actions

** Action Name ** ** Description **
specialoffer.created Creates a new special offer
specialoffer.updated Updates a special offer

(back to top)

Miscellaneous Related Webhooks/Actions

** Action Name ** ** Description **
review.added A product review has been added

(back to top)

Tests

$ npm install --dev
$ npm test

(back to top)

Support

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.

Contributing

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!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

(back to top)

Security

If you discover any securitys-related issues, please email security@salla.sa instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

(back to top)

Readme

Keywords

Package Sidebar

Install

npm i @salla.sa/webhooks-actions

Weekly Downloads

34

Version

1.0.2

License

ISC

Unpacked Size

50.8 kB

Total Files

21

Last publish

Collaborators

  • a.djedaini
  • m.aljefri
  • malshoubaki
  • ahmed-alkatheri
  • ahmed-amlas
  • muhammed-sh
  • nullish-one
  • mostafaezzeldin
  • ahmed3mmar
  • mostafanabawy
  • hossamelsawy
  • egkrinkel
  • zafari8
  • mohanad7afiz
  • thaifani
  • ilyasabdul94
  • thegeeky
  • asm_sh_ali
  • kulth00m
  • salla.dev
  • naderm91
  • zymawy
  • omersamli
  • mohammad-altamimi
  • a-athamneh-salla
  • osama-k-salla-sa
  • khaled.almqayyad
  • abdulrahman_salla
  • maher-salla
  • dev_fouda
  • 4bdullatif
  • dhassanali
  • taghreedaaa
  • dhafer
  • elzakzouk
  • ashraf.reda
  • ahsanzaman2489
  • awaiskazmisalla
  • ali.arsalan177
  • jojomak13
  • devlomingo
  • hamzasalla
  • ghofranesalla
  • shimaa_hussein
  • ios96salla
  • ossycodes
  • owieselshaikh
  • abady009
  • osameyy
  • halsairi
  • alialjishi
  • abbasshdev
  • alquhaitsalla
  • waleed.salla
  • abubakermoharram
  • anhaar-ali-salla
  • mohammed_ashraaf
  • ali-mhd
  • hassankotti
  • iabdallah
  • canarydev41
  • ibra-hassan
  • dev-tarek
  • adelgs
  • anasred
  • salahmyn
  • anass_at
  • jalmatari
  • s.alkhwlani