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 Stitchex 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 Stitchex 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. Stitchex 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 Stitchex for up to 48 hours, after which it will be discarded.

To configure Stitchex to send to your webhook, navitate to Settings → Webhooks, 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 Stitchex 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?