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 retreive 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:
# 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
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".
You may want to obfusate your webhook URL and consider it secret. All webhook URLs must be HTTPS URLs and should not be accessible via HTTP.
All messages send to the webhook will include the
webhook_identifier that can be found from your Settings → API Webhooks page. For some added security you could check that this value is correct.
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.
Occassionally 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).