Webhooks

Overview

Webhooks are part of the ShopCtrl Triggers functionality. There is a possibility to send webhooks to your external target applications after a certain event in ShopCtrl.

A trigger could be raised for different events connected with change on:

• orders
• products
• invoices
• shipments
• parcels
• purchase orders
• returns

Webhook main features:

• Support of basic HTTP authentication
• Prioritizing webhooks in the queue
• Customize payload using merge fields
• There is a possibility to add an HMAC signature and /or Client Certificate
• Retry mechanism If a webhook response was unsuccessful, it would retry up to 10 times. If the response still returns an error, an alert will be created.

How to create trigger with call webhook action

To setup automatic webhook call on certain events in ShopCtrl, we need to create trigger and add an action - Call Web hook.

For example, to create a trigger action that will call an external target after an order change:

1. Go to Configuration > Triggers.
2. Click Add to create a new trigger.
3. Select an Event after which you would like to fire a trigger - Order change.
4. Select a Shop.
5. Click the Add Action button and select a Call Webhook action from the list.
6. In the General tab, provide the URL of the endpoint that will receive a webhook.
7. (Optional) Mark the Queue items must be unique to prevent the creation of multiple calls for frequently changed entities.
8. (Optional) Provide the HMAC secret to sign the request.
9. (Optional) Paste in the Client Certificate to be added to each request.
10. On the Authentication tab, enter the user name and password used for basic HTTP authentication.
    
11. On the Payload tab, you can specify the Payload Mime type.
    • application/JSON
    • application/XML
    • text/plain
      

• Enter the Payload body according to the scheme chosen.
• You can add Mergefields to the payload. To check what merge fields you could use for the specific event type:
  • Click the Available Mergefields button.
  • (Optional) Specify the Order id to generate a dynamic list of available merge fields for the specific order.
  • Or click Show All Available Mergefields to load the generic order type merge fields list.
    

14. Enable the trigger.
15. Click Save or Save and Close.

Default webhook payloads

When webhooks are triggered, the payload sent by our system can vary depending on the type of entity and the event. If the payload configuration is not manually set, the system sends the default JSON payload for the event.

Key Notes:

• Payload fields differ based on the event and entity type.
• Fields are populated only if the relevant data is available at the time of the event. If not, they will appear as null.

Below is a detailed list of the trigger events and their corresponding fields in the entityData object:

Webhook Queue

After the trigger fires, the webhook will be added to the webhook queue and performed in the background. You can access the Webhook Queue table from the System > Webhook Queue page.
Here you have an overview of all webhooks sent, dates and response messages.