Webhooks

Salla's Webhooks allows you to easily set up fully automated notifications, as you get to be notified whenever your App receives payload/data from a merchant store. They are triggered when:

• A merchant installs an App
• An order or product is created in the merchant store.
• A coupon is applied, and much more

You can then use the information sent via webhooks to trigger other actions or integrate with external systems. This makes it simple to customize your notifications and keep track of all changes occurring within your Salla account.

Security Implementation

Salla secures webhook communication using headers. When an event occurs, Salla will send these headers and the relevant details to the specified App along with the token or signature verifies that the request is from Salla. Alternately, you can create a customized key and value to use with Salla's payload.

The following image illustrates how the Webhook communication is conducted in a secured vs insecured environment.

You can easily authenticate webhook calls using Salla's built-in options, which are Signature, and Token. The strategies are described in depth in the section that follows.

:::warning
Using Salla's tokens or signatures while POSTing data, allows you to authenticate the sender. Otherwise, deny any other suspicious requests.
:::

Regsiter Webhooks

There are noticeable, interchangeable parameters in the latest Salla API update. Let us take a look at the structures in both versions as we get responses from a webhook

When sending the parameters using any endpoints from Salla, there are common properties they share, although having different structure. For more on the hows to register a webhook, check either the previous section or this API.

:::warning
Salla currently uses API Version 2. By default, all new registered webhooks will be set as version 2. If you want to use version 1 of the webhook, pass that in your request parameter. Additionally, Salla will assign the Security Strategy to Signature by default in case you registered a webhook with no security strategy defined in your body request.
:::

Security Strategies

const express = require("express");
const crypto = require("crypto");

const app = express();

// Base Endpoint URL: https://api.salla.dev/admin/v2
app.post('/webhooks/subscribe', (req, res) => {
  const requestHMAC = req.header("x-salla-signature");
  const secret = process.env.WEBHOOK_SECRET;
  const computedHMAC = crypto.createHmac('sha256', secret).update(JSON.stringify(req.body)).digest('hex');
  const signatureMatches = requestHMAC === computedHMAC;
  
    if (!signatureMatches) {
      res.sendStatus(401);
  }

  // do stuff

  res.sendStatus(200);

<?php

$secret = getenv('WEBHOOK_SECRET');
$requestHMAC = $_SERVER['HTTP_X_SALLA_SIGNATURE'];
$requestBody = file_get_contents('php://input');
$computedHMAC = hash_hmac('sha256', $requestBody, $secret);

if ($requestHMAC === $computedHMAC) {
  // do stuff
}

http_response_code($requestHMAC === $computedHMAC ? 200 : 401);

const express = require("express");
const crypto = require("crypto");

const app = express();

// Base Endpoint URL: https://api.salla.dev/admin/v2
app.post('/webhooks/subscribe', (req, res) => {
  const requestHMAC = req.header("x-salla-signature");
  const secret = process.env.WEBHOOK_SECRET;
  const computedHMAC = crypto.createHmac('sha256', secret).update(JSON.stringify(req.body)).digest('hex');
  const signatureMatches = requestHMAC === computedHMAC;
  
    if (!signatureMatches) {
      res.sendStatus(401);
  }

  // do stuff

  res.sendStatus(200);

<?php

$secret = getenv('WEBHOOK_SECRET');
$requestHMAC = $_SERVER['HTTP_X_SALLA_SIGNATURE'];
$requestBody = file_get_contents('php://input');
$computedHMAC = hash_hmac('sha256', $requestBody, $secret);

if ($requestHMAC === $computedHMAC) {
  // do stuff
}

http_response_code($requestHMAC === $computedHMAC ? 200 : 401);

Timeout

The timeout indicates the amount of time the client must establish the connection. Salla will wait for the HTTP response and the initiation of the connection for around 30 seconds.

:::caution
If Salla did not get a successful response from the webhook endpoint, it would trigger the webhook event three times during the event. The interval between each trial will be around five minutes. In the case of receiving a successful response, no further requests will be sent.
:::

List of Salla Store Events

Order

Product

Shipping Companies

Shipments

Customer

Category

Brand

Store

Cart

Invoice

Special Offer

Miscellaneous

Troubleshooting

This section will go through why webhooks fail and what are the different scenarios you can do to troubleshoot such issues.

Why Webhook Fails

Abnormally, your webhook might not return any results after receiving a payload, and therefore Salla considers that as a failure request/response.

There are two probable explanations for why you are not receiving webhooks for your transactions:

• Because the webhook URL is not specified or the transaction is not in a final state, Salla is not delivering data to your hook URL (success or failed), or

• The requests are not being accepted by your webhook server.

The initial step in troubleshooting, regardless of the issue, would be to test for the situations.

Set Up Troubleshooting Environment

To troubleshoot for Salla webhooks, we will construct a workable URL from https://webhook.site/. This will act as our server, listening for Salla webhooks.

When an event occurs, the webhook data should be shown on the URL. This confirms that webhooks are being delivered to the developer/merchant's server.

Please follow the instructions below to carry out this test:

• Go to https://webhook.site/

• Copy the URL

  

• Navigate to the Webhooks Tab on the store's settings page.

• Create a new webhook

• Name your webhook and then select the event you want to listen to

• Paste the copied URL into the URL field, then save.

Now, go ahead and initiate an event. Go back to https://webhook.site/ after this event has occured on your end. You should see the webhook data for the most recent events on the webhook site.

If the webhook data is shown as in the screenshot above, it means that Salla is delivering the webhooks correctly and that the problem is most likely with your server.

:::note
You may also provide your header request parameters on the same page. Additionally, to build webhooks, you may use any API Request Builder, such as Hoppscotch or Postman.
Check out the Salla Webhooks doc page for additional information.
:::

After the Webhook environment is well-suited to start the troubleshooting, we will go through the following scenarios:

• Webhook Server Troubleshooting
• URL Endpoint Access Troubleshooting
• POST Data Troubleshooting

🔍 Webhook Server Troubleshooting

Following that, we'll see if your server is allowing requests to the webhook endpoint and whether you're receiving the provided POST data correctly.

Make sure to adjust the webhook URL to your own test endpoint from the Salla dashboard's Webhooks. And that would show you results based on that URL.

:::warning
Please verify that the activities performed in the testing endpoint do not affect your actual data.
:::

🔍 URL Endpoint Access Troubleshooting

This test will help you determine whether your webhook endpoint accepts requests from Salla. For this examination:

• Create a POST endpoint that, whenever a request is submitted to it, adds a timestamp to a log file.

• Create an event (for example: order) (if your webhook was setup for order creation).

• Examine the log file a few seconds after the request is done to see if it includes the written timestamp.

• Check for any TLS/SSL handshake failure

• Send and Inspect a POST request over to Salla

• Examine the receiving endpoint for errors

If a request log is there after the request attempt, it confirms that your server granted access to the endpoint as intended.

If it did not write to your log, there is a good probability that the request did not reach the endpoint or that your server rejected it; to resolve this, follow these steps:

• Ensure that the URL in the Salla webhook settings is correct and you can check Life active webhooks.

• Examine any responses from the POST call.

🔍 POST Data Troubleshooting

The following step is to ensure that you are receiving the POST Data appropriately.

This troubleshooting mechanism is quite similar to the one mentioned above. In this example, we'll obtain the content of the POST request and save it to a file.

Here's an example of a successful webhook body from the order.created event: