Webhooks

Required Permissions

An employee must be assigned to the shop with a Shop Owner Admin role to perform actions referred to in this article.

Overview

Webhooks are part of the ShopCtrl Triggers functionality. With the Call Webhook action, ShopCtrl sends a request to your external application when a certain event happens in ShopCtrl.

A webhook can be sent for events in these areas:

• Orders
• Invoices
• Shipments and parcels
• Returns
• Products
• Purchase orders
• Stock counts
• Customers
• Tickets
• Service and rental contracts
• Shops
• VoIP calls

For the full list, see Trigger events.

Webhook main features:

• Basic HTTP authentication with a username and password.
• Priority - webhooks with a higher priority are sent first from the queue.
• Custom payload built with merge fields, or a default payload for each event.
• HMAC signature - ShopCtrl signs the request body with HMAC-SHA512 using your secret, and sends the signature as a lowercase hex string in the X-SIGNATURE header.
• Client certificate added to each request.
• Unique queue items - optionally skip a webhook if the same one is still waiting in the queue.
• Retries - if a webhook fails, ShopCtrl tries again, up to 10 attempts by default. The wait grows with each attempt: 90 seconds after the first failure, 180 seconds after the second, and so on. If the last attempt fails, an alert is 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.

Please note

Leave the payload empty to send the default payload in JSON. The default payload depends on the event type of the trigger, see Default webhook payloads.

Default webhook payloads

If you leave the payload empty, ShopCtrl sends a default JSON payload. Every webhook, with a default or a custom payload, is sent in the same wrapper:

{
  "Trigger": "ShipmentShipped",
  "TriggerActionId": 123,
  "Data": {
    "ParcelId": 4567,
    "TrackingCode": "3SABCD1234567",
    "OrderShipmentId": 890,
    "OrderShipmentCode": "SH-10025",
    "OrderId": 1234,
    "OrderCode": "SO-10025"
  }
}

• Trigger - the event that fired the trigger, as its system name without spaces, for example OrderMainStatusChanged or ShipmentShipped.
• TriggerActionId - the ID of the Call Webhook action that sent the request.
• Data - the default fields for the event, listed below. If you set a custom payload, Data contains your payload instead.

Fields are filled in only if the data is available when the event happens. A missing ID is sent as null. For shipment and return events, a missing code is sent as an empty string ("").

Trigger event	Fields in Data
Product created Product changed Product deleted Product available stock changed Product locked Product unlocked Product dimensions changed	ProductId ProductCode ShopGroupId
Product package created Product package changed Product package deleted	ProductPackageId ProductId ShopGroupId
Product selection product changed Product selection product deleted	ProductId ProductCode ProductSelectionProductId ShopId
Product group changed Product group deleted	ProductGroupId ProductGroupName
Product property definition changed Product property definition deleted	Id Code
Product brand changed Product brand deleted	Id Name
Order customer rating changed	OrderId OrderCode CustomerRating
Order comment changed	OrderCommentId OrderId OrderCode TicketId TicketCode
Invoice payments done Invoice payments not done Invoice payments partial done Non-draft invoice saved Non-draft credit invoice saved Order invoices all paid Order invoices partial paid Order invoices created	InvoiceId InvoiceCode OrderId OrderCode
Shipment created Shipment picked Shipment packed Shipment shipped Shipment handover Shipment delivered New parcel added Parcel status change Parcel pickup done Order shipment status changed Order fully shipped	ParcelId TrackingCode OrderShipmentId OrderShipmentCode OrderId OrderCode
Return created Return changed Return main status changed	OrderReturnId OrderReturnCode OrderId OrderCode
Purchase order created Purchase order custom status changed Purchase order delivery provisioned Purchase order delivery received Purchase order handed over Purchase order main status changed Purchase order payment status changed Purchase order provision status changed Purchase order provisioned Purchase order received Purchase order submit status changed	PurchaseOrderId PurchaseOrderCode SupplierId WarehouseId OrderId OrderCode ShopId
Ticket created Ticket main status changed	TicketId TicketCode OrderId OrderCode ShopId
Ticket handling employee group changed	TicketId TicketCode OrderId OrderCode ShopId HandlingEmployeeGroupId OldHandlingEmployeeGroupId
Ticket handling employee changed	TicketId TicketCode OrderId OrderCode ShopId HandlingEmployeeId OldHandlingEmployeeId
Ticket incoming message Ticket outgoing message	TicketId TicketCode OrderId OrderCode ShopId TicketMessageDirection
Ticket satisfaction score changed	TicketId TicketCode OrderId OrderCode ShopId SatisfactionScoreOld SatisfactionScore
Service contract active status changed	ServiceContractId ServiceContractCode ShopId ActiveStatus ActiveStatusName OldActiveStatus OldActiveStatusName
Rental contract active status changed	RentalContractId RentalContractCode ShopId ActiveStatus ActiveStatusName OldActiveStatus OldActiveStatusName
Rental contract order created	RentalContractId RentalContractCode ShopId OrderId OrderCode
Init new shop New shop saved	ShopId
Voip call changed	Id
All other events linked to an order	OrderId OrderCode
All other events without an order	A list of Id and Type pairs, one for each entity involved in the event

For the full list of events, see Trigger events.

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.