Real time integration using webhooks

In a unified commerce best of breed solution, having your integrations running in real time is recommended.
This makes sure that you, you colleagues and not to mention your customers enjoy a smooth user experience and customer journey.
In this guide you will learn how to subscribe to our webhooks and our best practises making sure you dont loose any events in case of system downtime on any sides.

Webhooks

You can use webhook subscriptions to receive notifications about particular events in a store. After you've subscribed to a webhook, your integrated system can execute your code immediately instead of having to make API calls periodically to check their status.

For example, when an sale is completed in the store using the POS, your ERP can immediately get the sale registered. Or when the in-store stockleves change, your eCom will immediately expose the new stock levels to your online shoppers.
By using webhooks, you can make fewer API-calls overall, reducing both time to develop and maintain your integrations.

Webhook Events Overview

SaleCreated
- Trigger: When a sales transaction is completed in the POS.
- Usage: To update ERP or other accounting systems with relevant sale details.
CustomerCreated
- Trigger: When a new customer is added, typically related to a POS sale.
- Usage: For tracking and managing new customers.
CustomerUpdated
- Trigger: When an existing customer's information is updated in the POS.
- Usage: For keeping customer details up-to-date.
DeliveryItemsReceived
- Trigger: When a delivery is partially or fully received.
- Usage: For tracking stock movements of newly received items in ERP.
DeliveryCompleted
- Trigger: When a delivery is completed and archived.
- Usage: For recording final stock movements in ERP associated with a delivery.
InvoiceCreated
- Trigger: When a sale is completed with the invoice as the payment method.
- Usage: For processing the invoice in ERP or other invoicing tools.
StockMovementCreated
- Trigger: When any stock movement occurs, such as sale, return, adjustments, etc.
- Usage: For real-time synchronization of stock quantities with other systems.
OmniChannelEndlessAisleOrderCreated
- Trigger: When an endless aisle order is created in the POS.
- Usage: For tracking and fulfilling specific types of orders.
OmniChannelOrderFulfilled
- Trigger: When an omnichannel order is fulfilled in the POS.
- Usage: For marking orders as completed.
OmniChannelOrderRefundUpdated
- Trigger: When an online order is refunded in the POS.
- Usage: For processing and tracking refunds.
OmniChannelOrderUpdated
- Trigger: When an omnichannel order is updated in the POS.
- Usage: For maintaining accurate order details.
ProductTransferCreated
- Trigger: When a product transfer between locations is initiated.
- Usage: For managing inter-location stock transfers.
ProductTransferReceived
- Trigger: When a product transfer is received.
- Usage: For updating stock levels upon receipt.
ProductTransferVirtualCreated
- Trigger: When a virtual product transfer is initiated (items transferred to or from a virtual stock)
- Usage: For tracking virtual stock movements.
ProductTransferVirtualReceived
- Trigger: When a virtual product transfer is received.
- Usage: For adjusting virtual stock levels.
SaleExternalCreated
- Trigger: When a sales transaction is added externally, like online sales.
- Usage: For integrating external sales into the system.
StockAdjustmentCreated
- Trigger: When a stock adjustment is made.
- Usage: For correcting or reconciling stock levels.
StockCountReconciled
- Trigger: When a stock count is reconciled. Will also trigger when api/stock/adjust is used.
- Usage: For finalizing stock counts and adjusting levels in ERP. Payload contains all reconciled items/stockmovements created. If you need the complete all hand quantity, use the StockStatus endpoint with use of the snapShotDateTime parameter = the time of the countedDateTime + a couple of seconds.
POSSettlementCreated
- Trigger: When a POS settlement (Z report) is performed.
- Usage: For updating ERP or accounting systems with end-of-day figures.

New event types are added every now and then. An real-time overview of what kind of types of webhook events you can subscribe to make a call to
GET /api/WebhooksTypes

Schema

To learn what kind of schema a specfic type uses, make a call to
GET /api/WebhooksTypes/{webhookType}/schema

Subscribing to an webhook event is done by
POST /api/webhooks

Heres an example how to subscribe to an endless aisle webhook

{
   "event": "OmniChannelEndlessAisleOrderCreated",
   "url": "https://yourcallback.com/url"
}

Resend events

In case a webhook event gets lost on its way you can get it resent.

For example, in case your subscribing endpoint had a failure due to network issues, maintenance work or similar when we where sending events to you, you can easily get those listed. Without a http 2xx back, Front Systems don't know if the request reached the endpoint or not. Since many of the legacy ERP systems don't have idempotent endpoints, we have decided to not include automatic resend, but leave the integrity check up the the integrator.

We recommend that you periodically, (eg once per day or week) check that you have received all events.

Its super easy to implement using GetWebHooksEvents

Here is s an example
GET /api/WebhooksEvents/edd10354-7625-4f29-bd9f-e43c61cf2eba?from=2021-12-01&to=2021-12-15&success=false&includePayload=false&includeRuns=false

[ 
   { 
    "webhookId": "edd10354-7625-4f29-bd9f-e43c61cf2ebe",
    "webhookEventId": "b38832a2-b522-4b2d-ba10-5f217a9efbc1", 
    "createdDateTime": "2021-12-09T08:50:46.02", 
    "updatedDateTime": null, 
    "status": "Not found", 
    "statusCode": 404, 
    "success": false, 
    "runsCounter": 1, 
    "runs": [] 
   } 
]

(If you includePayload, you can will be able to see the payload of the original event)

And then use ResendWebhookEvent to resend the ones not retrieved. If your back-end is idempotent, then you can make a small service to resend all failed events on a regular basis (until GetWebHooksEvents success=false return an empty payload)

Real time integration using webhooks

Webhooks

Webhook Events Overview

Schema

Subscribe

Read more details here

Resend events