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 which Uphance will send data when the specific event occurs. Events currently supported are shown in the screenshot below. The webhook will typically be sent an ID number with which you can retrieve more data with an appropriate GET request to the Uphance API.
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".
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).