Webhooks

Subscribing to webhooks

By using the v1/Webhooks/GetTypes GET endpoint, all available webhooks can be requested.

To subscribe, use the /v1/Webhooks POST endpoint with the following parameters:

Group: {Group}
Event: {Event}
URL: {URL where you would like to receive the push-notification when the webhook is triggered}

Checking subscribed webhooks

By using the v1/Webhooks/GetWebhookUrl GET endpoint, you can check all webhook subscriptions. You can also check the subscription(s) for a specific webhook by applying the following parameters:

Group: {Group}
Event: {Event}

Unsubscribing from webhooks

To unsubscribe, use the v1/Webhooks DEL endpoint with the following parameters:

Group: {Group}
Event: {Event}
URL: {URL}

Automated retries

If OIS does not receive a '200 OK' response when a webhook is triggered, the payload will be retried three times:

• After 30 seconds

• After 5 minutes

• After 1 hour

After the third retry there are no further retries. In cases where external systems are down for extended periods of time, resulting in missed payloads, two options are available to search and retry them.

• In OIS Configuration under 'Monitoring' the tab 'Webhooks' is available. Here, the response status code and response message can be viewed for any failed payloads. The payload itself can be viewed and triggered again.

• OIS endpoints can be used to retrieve payloads for a specific status and retry them, see 'Retrieving triggered payloads' below.

Retrieving triggered payloads

To retreive previously triggered webhook messages, you can either retrieve a paginated list of triggered webhooks, or a single webhook trigger if you know the specific identifier. This is mainly used in case there are payloads that have the status 'failed', even after automated retries.

Paginated list of messages - use the v1/webhooks/status GET endpoint with the following parameters:

Page: {The page you want to view}
PageSize: {The amount of results that should be shown per page}
Status: {The status you want to filter for}

For example, a list of all payloads with the status 'failed' can be retrieved. A unique Identifier is available per payload, with which the v1/Webhooks/Status/Identifier POST endpoint can be used to retry those payloads.

Available webhooks

Below are all available webhooks, ordered by Group.

Group: Order

• OrderCancelled - "group": "Order" - "event": "Cancelled"

  Is triggered when an order or individual orderlines are cancelled. An order or individual orderlines can be cancelled in the following ways:

  • Delivered from ERP to OIS.

  • By using the '/api/v1/Order/{OrderId}/OrderLines/Cancel' and '/api/v1/Order/{OrderNumber}/OrderLines/CancelByOrderNumber' endpoints.

  • By using the Customer Service application of the Retail Suite.

  Payload: {"OrderId":"{OrderId}","CancelledVariantIds":[{CancelledVariantIds}],"Source":"{Source}"}

• OrderCreated - "group": "Order" - "event": "Created"

  Is triggered when an order is POSTed to the OIS. An order can be created in the following ways:

  • An Order POST to the '/api/v1/Order' or '/api/v1/Order/{WebshopCode}' endpoints.

  • By using the Digital Sales Assistant application of the Retail Suite. Note that the webhook is not triggered until payment is confirmed.

  Payload: {"Id":"{OrderId}"}

• OrderCreditMemoCreated - "group": "Order" - "event": "CreditMemoCreated"

  Is triggered when a CreditMemo is added to an order. A CreditMemo can be added in the following way:

  • Delivered from ERP to OIS.

  Payload: {"OrderId":"{OrderId}","CreditMemoNo":"{CreditMemoNo}"}

• OrderDiscount - "group": "Order" - "event": "DiscountAdded"

  Is triggered when a discount is added to an order or individual orderlines. A discount can be added in the following ways:

  • By using the '/api/v1/Order/{OrderId}/OrderLines/Discounts' endpoint.

  • By using the Customer Service application of the Retail Suite.

• OrderDocumentCreated - "group": "Order" - "event": "OrderDocumentCreated"

  Is triggered when any OrderDocument is made available. An OrderDocument can be made available in the following way:

  • Delivered from ERP to OIS

  • By using the Order Circulation application of the Retail Suite

  Payload: {"OrderId":"{OrderId}", "DocumentIdentifier":"{DocumentIdentifier}", "DocumentName":"{DocumentName}"}

• OrderNotFulfilled - "group": "Order" - "event": "NotFulfilled"

  Is triggered when a pickrequest cannot be fulfilled. A pickrequest can be rejected in the following way:

  • By using the Order Circulation application of the Retail Suite.

  Payload: {"OrderId":"{OrderId}","CancelledVariantIds":[{CancelledVariantIds]}

• OrderPaymentLinkAvailable - "group": "Order" - "event": "PaymentLinkAvailable"

  Is triggered when an order has been placed with the PaymentMethod 'PayPerMail'. This can be done in the following way:

  • By using the Digital Sales Assistant application of the Retail Suite.

  Payload: {"OrderId":"{OrderId}", "Url":"{Url}"}

• OrderPicked - "group": "Order" - "event": "Picked"

  Is triggered when orderlines are picked.

  • Orderlines are picked when a user confirms a pickrequest in the Order Circulation application of the Retail Suite. If a pickrequest is assigned to a stocklocation that is set to 'Auto Accept' in the order circulation algorithm, this happens automatically.

  Payload: {"OrderId":"{OrderId}","ShipmentIdentifier":"{ShipmentIdentifier}","OrderVariantIds":[{OrderVariantIds],"BranchCode":"{BranchCode"}

• OrderReturned - "group": "Order" - "event": "Returned"

  Is triggered when an order or individual orderlines are returned and confirmation is sent to OIS. This confirmation can be sent in the following ways:

  • Delivered from ERP to OIS.

  Payload: {"Id":"{OrderId}","OrderVariantIds":[{OrderVariantIds}],"Source":"{Source}","BranchCode":{BranchCode}}

• OrderReturnPrenotified - "group": "Order" - "event": "ReturnPrenotified"

  Is triggered when OIS receives a notification an order or specific orderlines will be returned. Return notifications can be sent in the following ways:

  • By using the '/api/v1/Order/{OrderId}/OrderLines/PrenotifyReturn' endpoint.

  Payload: {"Id":"{OrderId}","OrderVariantIds":[{OrderVariantIds}],"Source":{Source},"TrackTrace":{TrackTrace}}

• OrderSEPACreated - "group": "Order" - "event": "SEPACreated"

  Is triggered when a SEPA message has been created. A SEPA message can be created in the following ways:

  • Delivered from ERP to OIS.

  Payload: {"OrderId":"{OrderId}","OrderVariantIds":"[{OrderVariantIds}],"BankAccountHolder":"{BankAccountHolder}","BankAccountNumber":"{BankAccountNumber}","Bic":"{Bic}"}

  Note: For security reasons, BankAccountHolder and BankAccountNumber are likely to be removed from this webhook in the future, at which point an alternative method to retrieve SEPA messages will be provided.

Group: Customer

• CustomerCreated - "group": "Customer" - "event": "Created"

  Is triggered when a new customer account is created. A new customer account can be created in the following ways:

  • By using the Digital Sales Assistant application of the Retail Suite.

Group: Loyalty

• LoyaltyCouponCreated - "group": "Loyalty" - "event": "CouponCreated"

  Is triggered when a new coupon created and confirmation is delivered to OIS. This confirmation can be sent in the following way:

  • Delivered from ERP to OIS

  Payload: {"Amount":{Amount}, "Code":"{Code}", "CustomerNumber":"{CustomerNumber}", "ReferenceNumber":"{ReferenceNumber}"}

• LoyaltyCouponIncreased - "group": "Loyalty" - "event": "CouponIncreased"

  Is triggered when an existing coupon has been updated and confirmation is delivered to OIS. This confirmation can be sent in the following way:

  • Delivered from ERP to OIS.

  Payload: {"NewAmount":{NewAmount}, "PreviousAmount":{PreviousAmount}, "Code":"{Code}", "CustomerNumber":"{CustomerNumber}", "ReferenceNumber":"{ReferenceNumber}"}

• LoyaltyCouponRedeemed - "group": "Loyalty" - "event": "CouponRedeemed"

  Is triggered when a coupon has been used and confirmation is delivered to OIS. This confirmation can be sent in the following way:

  • Delivered from ERP to OIS.

  Payload: {"NewAmount":"NewAmount","PreviousAmount":"PreviousAmount","Code":"Code","CustomerNumber":"CustomerNumber","ReferenceNumber":"ReferenceNumber"}

Group: Shipment

• ShipmentCreated - "group": "Shipment" - "event": "Created"

  Is triggered when a shipment is sent to a customer. Shipments can be sent in the following ways:

  • In ERP.

  • By using the '/api/v1/OrderShipment' and '/api/v1/OrderShipment/AddByOrderNumber' endpoints. Note that using these endpoints will cause a SHIPMENT.xml to be delivered from OIS to ERP.

  Payload: {"OrderId":"{OrderId}","ShipmentIdentifier":"{ShipmentIdentifier}","ExternalId":"{ExternalId}","TrackTrace":"{TrackTrace}","OrderVariants":[{OrderVariants}],"Source":"{Source}","BranchCode":"{BranchCode}"} 

• ShipmentPickedUp - "group": "Shipment" - "event": "PickedUp"

  Is triggered when an order has been picked up at a store. This notification can be sent in the following way:

  • By using the Instore Pickups application of the Retail Suite.

  Payload: {"ShipmentIdentifier":"{ShipmentIdentifier}"}

• ShipmentReceivedAtBranch - "group": "Shipment" - "event": "ReceivedAtBranch"

  Is triggered when an order has been delivered to a store, to notify the customer their order can be picked up. This notification can be sent in the following way:

  • By using the Instore Pickups application of the Retail Suite.

  Payload: {"ShipmentIdentifier":"{ShipmentIdentifier}"}

Group: ProductComplaint

• ProductComplaintCreated - "group": "ProductComplaint" - "event": "Created"

  Is triggered when a new product complaint is registered. Product complaints can be registered in the following ways:

  • By using the Product Complaints application of the Retail Suite.

  Payload: {"ProductComplaintId":"ProductComplaintId"}