Webhooks

Vereiste rechten

Een medewerker moet met de rol Shop Owner Admin aan de shop gekoppeld zijn om de acties in dit artikel uit te voeren.

Overzicht

Webhooks maken deel uit van de Triggers in ShopCtrl. Met de actie Call Webhook stuurt ShopCtrl een verzoek naar uw externe applicatie wanneer er een bepaalde gebeurtenis in ShopCtrl plaatsvindt.

Een webhook kan worden verstuurd bij gebeurtenissen in deze onderdelen:

• Orders
• Facturen
• Zendingen en pakketten
• Retouren
• Producten
• Inkooporders
• Voorraadtellingen
• Klanten
• Tickets
• Service- en huurcontracten
• Shops
• VoIP-gesprekken

De volledige lijst vindt u in Trigger-gebeurtenissen.

Belangrijkste functies van webhooks:

• Basis-HTTP-authenticatie met een gebruikersnaam en wachtwoord.
• Prioriteit - webhooks met een hogere prioriteit worden als eerste uit de wachtrij verstuurd.
• Eigen payload opgebouwd met merge fields, of een standaardpayload per gebeurtenis.
• HMAC-handtekening - ShopCtrl ondertekent de inhoud van het verzoek met HMAC-SHA512 en uw secret, en stuurt de handtekening als hexadecimale tekenreeks in kleine letters mee in de header X-SIGNATURE.
• Clientcertificaat dat aan elk verzoek wordt toegevoegd.
• Unieke items in de wachtrij - sla optioneel een webhook over als dezelfde webhook nog in de wachtrij staat.
• Nieuwe pogingen - als een webhook mislukt, probeert ShopCtrl het opnieuw, standaard maximaal 10 keer. De wachttijd wordt bij elke poging langer: 90 seconden na de eerste mislukte poging, 180 seconden na de tweede, enzovoort. Als de laatste poging mislukt, wordt er een melding aangemaakt.

Een trigger met de actie Call Webhook aanmaken

Om bij bepaalde gebeurtenissen in ShopCtrl automatisch een webhook aan te roepen, maakt u een trigger aan en voegt u de actie Call Web hook toe.

Een Trigger-actie aanmaken die bijvoorbeeld na een wijziging van een order een extern doel aanroept:

1. Ga naar Configuration > Triggers.
2. Klik op Add om een nieuwe trigger aan te maken.
3. Selecteer de Event waarna u de trigger wilt uitvoeren: Order change.
4. Selecteer een Shop.
5. Klik op de knop Add Action en selecteer de actie Call Webhook in de lijst.
6. Vul op het tabblad General de URL in van het endpoint dat de webhook ontvangt.
7. (Optioneel) Vink Queue items must be unique aan om te voorkomen dat er meerdere aanroepen worden aangemaakt voor records die vaak wijzigen.
8. (Optioneel) Vul het HMAC secret in om het verzoek te ondertekenen.
9. (Optioneel) Plak het Client Certificate dat aan elk verzoek wordt toegevoegd.
10. Vul op het tabblad Authentication de gebruikersnaam en het wachtwoord voor basis-HTTP-authenticatie in.
11. Op het tabblad Payload kunt u het Payload Mime type opgeven. _ application/JSON _ application/XML * text/plain

• Vul de inhoud van de Payload in volgens het gekozen schema.
• U kunt Mergefields aan de payload toevoegen. Om te zien welke merge fields u voor het betreffende type gebeurtenis kunt gebruiken:
  • Klik op de knop Available Mergefields.
  • (Optioneel) Geef het Order id op om een dynamische lijst met beschikbare merge fields voor die order te genereren.
  • Of klik op Show All Available Mergefields om de algemene lijst met merge fields voor orders te laden.

14. Schakel de trigger in met Enable.
15. Klik op Save of Save and Close.

Let op

Laat de payload leeg om de standaardpayload in JSON te versturen. De standaardpayload hangt af van het type gebeurtenis van de trigger; zie Standaardpayloads voor webhooks.

Standaardpayloads voor webhooks

Als u de payload leeg laat, stuurt ShopCtrl een standaardpayload in JSON. Elke webhook, met een standaardpayload of een eigen payload, wordt in dezelfde omhulling verstuurd:

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

• Trigger - de gebeurtenis die de trigger heeft gestart, als systeemnaam zonder spaties, bijvoorbeeld OrderMainStatusChanged of ShipmentShipped.
• TriggerActionId - het ID van de actie Call Webhook die het verzoek heeft verstuurd.
• Data - de standaardvelden voor de gebeurtenis, zie hieronder. Als u een eigen payload instelt, bevat Data in plaats daarvan uw payload.

Velden worden alleen gevuld als de gegevens beschikbaar zijn op het moment van de gebeurtenis. Een ontbrekend ID wordt als null verstuurd. Bij gebeurtenissen voor zendingen en retouren wordt een ontbrekende code als lege tekenreeks ("") verstuurd.

Trigger-gebeurtenis	Velden 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
Alle andere gebeurtenissen die aan een order zijn gekoppeld	OrderId OrderCode
Alle andere gebeurtenissen zonder order	Een lijst met paren van Id en Type, één voor elk record dat bij de gebeurtenis betrokken is

De volledige lijst met gebeurtenissen vindt u in Trigger-gebeurtenissen.

Wachtrij voor webhooks

Nadat de trigger is uitgevoerd, wordt de webhook aan de wachtrij voor webhooks toegevoegd en op de achtergrond verstuurd. De tabel Webhook Queue vindt u op de pagina System > Webhook Queue. Hier ziet u een overzicht van alle verstuurde webhooks, met datums en antwoordberichten.