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
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.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 webhookWhen 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.| Parameter | Type | Description |
|---|
| name | string | Webhook Name |
| event | string | Webhook Event From Event List |
| version | number | Webhook Version; of the webhook; either valued as 1 or 2. |
| rule | string | Operations, expressions and conditions to your webhook. For example, you may use =,!=,AND,OR etc in such a menner: payment_method = YOUR_PAYMENT_METHOD or in combination payment_method = mada OR price < 50. That adds more capbility to filter the response based on conditions |
| url | string | Webhook URL where you will receive the webhook calls |
| headers | array[object] | Webhook headers containing security info |
| headers.key | string | Any haeder key, which its value is sent in the post request to the webhook URL |
| headers.value | string | The value sent to the webhook; for example: cf-ray: 669af54ecf55dfcb-FRA |
| secret | string | Secret Token value |
| version | string | Webhook Version; either valued as 1 or 2. |
| rule | string | Operations, expressions and conditions to your webhook. For example, you may use =,!=,AND,OR etc in such a menner: payment_method = YOUR_PAYMENT_METHOD or in combination payment_method = mada OR price < 50. That adds more capbility to filter the response based on conditions. Read more here |
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#
For all created
Partner Apps, Salla will assign the
signature security strategy by default, as Salla will hash payloads via an auto-generated, reproducable signature token. It will also append two headers to the webhook payload; the security startegy used as in
X-Salla-Security-Strategy which is in this context
Signature , and a hashed token signature as in
4d7dac8e688eca1c1xxxx| Security Startegy | Header | Token Suffix |
|---|
| Signature | X-Salla-Security-Strategy | X-Salla-Signature |
Register Endpoint#
Following is the expected request payload for the Signature security strategy:Verify Webhooks Using Signature#
Once merchants install the app in their stores, Salla uses the Siganture secret startegy (or the default one on app settings) to automatically assign webhook events.A value for Secret must be given when establishing the webhook in order to allow webhook verification. The request body's 64 character SHA256 hash, which you may find via your partner's dashboard, will then be appended to the X-salla-signature header (e.g. x-salla-signature: ac3ea83628cccf2e98afc34223e4eeb5b41800b77737938aeed4e109f0a0xxxx).You can also create your own SHA256 hash of the request body using the Secret value to check the signature. Then, using a timing-safe equality function, compare the header value to your own calculated value. Here is an example of how you might accomplish this using Node.js.Another demonstration can be done using the PHP language to verify a webhook header when receiving a payload. Once the webhook is received, your server can verify it from Salla in the following way: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.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#
| Name | Description |
|---|
shipment.creating | This is triggered when a shipment is assigned to a shipping company. |
shipment.created | This is triggered when shipment is updated by the shipping company for the first time. |
shipment.cancelled | This is triggered when a shipment is cancelled. |
shipment.updated | This is triggered when a shipment is updated after creation. |
Customer#
| Name | Description |
|---|
customer.created | This event is triggered when a customer has been created. |
customer.updated | This event is triggered when a customer has been updated. |
customer.login | This event is triggered when a customer has logged in to their account. |
customer.otp.request | This event is triggered when a customer's One-Time Password has been requested. |
Category#
| Name | Description |
|---|
category.created | This event is triggered when a category has been created. |
category.updated | This event is triggered when a category has been updated. |
Brand#
| Name | Description |
|---|
brand.created | This event is triggered when a brand has been created. |
brand.updated | This event is triggered when a brand has been updated. |
brand.deleted | This event is triggered when a brand has been deleted. |
Store#
Cart#
| Name | Description |
|---|
abandoned.cart | This event is triggered when an abandoned cart has been created. |
coupon.applied | This event is triggered when a coupon has been applied. |
Invoice#
| Name | Description |
|---|
invoice.created | This event is triggered when the order status is either completed or restored. |
Special Offer#
Miscellaneous#
| Name | Description |
|---|
review.added | This event is triggered when a product's review has been added. |
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.
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:Name your webhook and then select the event you want to listen to
Paste the copied URL into the URL field, then save.
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. 🔍 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.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
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: 
扫码加入交流群