Use webhooks from the Uphance API for real-time two-way integration

Mike Maloney avatar
Written by Mike Maloney
Updated over a week ago

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

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".


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).

Next steps

Did this answer your question?