Understanding how 23shout incorporates REST hooks to make your app better
Overview
Polling for information is the old way of doing things, the new and more exciting (not to mention efficient) method is to use REST hooks.
REST hooks mean that instead of periodically check for updates to an object in our API, we'll instead notify you when a change occurs to a URL of your choice.
If you've used REST hooks before then you know the score, but this article and it's sub-articles will contain some useful information for you such as endpoints, and authenticating messages came from 23shout.
If not, then executive summary is that while using the 23shout API you're able to subscribe to certain changes from 23shout, for example whether or not your message was delivered, or your call was made. To subscribe to these, you give 23shout a URL for every change made. For example, if I sent a message using the 23shout API and its ID was given to me as 123, I might subscribe to updates for this message to a URL at https://example.com/message/updates and listen for any updates to a message with the ID 123.
Usually these URLs however will be unique, for example I'll subscribe to updates when sending the message to a URL with a UUID in it, such as https://example.com/message/updates/19a7dfec-189e-406d-9aab-95660abbf40e, and then log this UUID into my database and perform a lookup every time updates are delivered to this URL.
When I want to stop receiving updates, I can perform a DELETE request to the 23shout API endpoint for this hook, and the updates will be removed.
Verifying a request was legitimate
Since these URLs you provide are usually open to the public web, in order to verify a request does in fact come from 23shout we include the secret_access_key used to create the REST hook in the headers of every request. This allows you to make a direct comparison to the secret in your server environment and reject messages that don't compare.
Since you're not able to use a non https scheme URL, and since the key ID is not included, this is indeed a secure method.
Take this code for example written for Python Flask that compares the incoming request header and perform a check to ensure it matches the secret stored in our Environment Variables.
import os
from flask import request, Response
@app.route('/callbacks/<callback_id>')
def rest_hooks_callback(callback_id):
# If the access key doesn't match, return an Access Denied response.
if request.headers.get('secret_access_key') != os.environ.get('SHOUT_ACCESS_KEY_SECRET'):
return Response(status=401, response="Access denied")
# The rest of your applications code would be here.
return Response(response="Got it, thanks!")