You can set up a "webhook" to receive instant notification of specific events so as to execute relevant code in your application. You should always use a webhook rather than poll the API for new records or updates to existing data.
A webhook is a URL that you provide to Uphance. Uphance sends data to this URL when a specific event occurs. The webhook typically includes an ID that you can use to retrieve additional data through the appropriate GET request from the Uphance API.
The events currently supported are listed below:
Stock adjustment
Pick ticket creation
Pick ticket deletion
Pick ticket update
Receiving Ticket creation
Receiving Ticket deletion
Receiving Ticket update
Sale order creation
Sale order deletion
Sale order update
Production order creation
Production order deletion
Production order update
Product creation
Product deletion
Product update
Customer creation
Customer deletion
Customer update
Invoice creation
Invoice deletion
Invoice update
Return checkin
Return creation
Return update
Return deletion
Credit Note creation
Credit Note deletion
Credit Note update
Refund creation
Refund deletion
Invoice payment creation
Invoice payment update
Invoice payment delete
Creating a webhook
You'll need to add a web action to your own server application to handle webhook requests. This action should be accessible by HTTPS only. Uphance will not send webhook events to HTTP URLs.
Here is an example webhook endpoint written with Sinatra:
require "json"
# Using Sinatra
post "/my/secret/webhook/url" do
# Retrieve and parse the JSON request body
event_data = JSON.parse(request.body.read)
# Do something with event_data
status 200
end
You should return a response code in the 2XX range if you successfully handled the webhook event. If you return anything else the webhook request will be retried by Uphance for up to 48 hours, after which it will be discarded.
To configure Uphance to send to your webhook, navigate to Apps > Uphance API, click "New Webhook".
Every body has the same shape: the event name, plus one object keyed by the payload key for that event.
{
"event": "production_order_update",
"production_order": { "id": 1234, "production_order_number": "PO-1234", "...": "..." }
}Delete events send the id alone:
{
"event": "production_order_delete",
"production_order": { "id": 1234 }
}
Security
You may want to obfuscate your webhook URL and consider it secret. All webhook URLs must be HTTPS URLs and should not be accessible via HTTP.
Best practices
You should avoid running potentially complex or long-running tasks in your webhook action handler. Long running tasks are likely to timeout the webhook request and cause Uphance to assume failure and resend the webhook. If you need to perform a complex operation consider immediately returning a 2XX response code and performing your task asynchronously.
Occasionally the same event may be posted to your webhook handler more than once. This may happen if network connectivity is disrupted or for other reasons. You should therefore make sure that your webhook event handling code idempotent (possible by ignoring duplicate events and returning a 2XX response code).