Writing a POST Handler

Tutorials / Web Hooks

Introduction

Webhooks.org defines web hooks as "user-definable callbacks over HTTP."

Web hooks in Sitellite allow you to specify one or more URLs that will receive an HTTP POST request when certain workflow events occur. For example, your external applications can receive notifications whenever a page is added, modified or deleted. They can log this info or implement additional workflow actions based on it.

An example might be an external search tool that gets a notification whenever a page changes so it knows to re-index the page. Another example would be an external site that is notified of news stories as they're added to your site, possibly for syndication purposes. 

Specifying your URLs

To specify the URLs you would like to POST to:

1. Log into Sitellite and go to the Control Panel.
2. Under the Admin menu, choose Applications.
3. Click on the Edit icon next to the Content Manager application.
4. Enter your URL(s) into the Web Hooks text box, one per line.
5. Under the "Web Hooks Authorization Key" field, click Auto-Generate to generate a random authorization key. Save this value for later.
6. When you're finished, click Save.

Enabling Web Hooks

Now that you've specified your post-back URLs, you still need to enable the web hooks workflow service. To do this:

1. Go to the Control Panel.
2. Under the Admin menu, choose Workflow Services.
3. Under the Content Manager heading, check the checkbox next to Web Hooks.
4. Click Save. 

POST Parameters

Each POST request is sent certain parameters or information about the workflow event that occurred in Sitellite. These include:

auth – The authorization key for verifying that the request originated from your website. 

event – The workflow event that occurred. This can be one of: add, edit, delete, pre-delete or error.

summary – A summary message of the event.

action – If the event is 'edit' there is an action that specifies the type of edit. This can be one of: modify, replace, republish or update. Each of these correspond to status changes in Sitellite's internal workflow.

collection – If the event is an add, edit, delete or pre-delete, this will specify the collection name (e.g., sitellite_page).

key – If the event is an add, edit, delete or pre-delete, this will contain the primary key of the item.

changelog – If the event is an add, edit, delete or pre-delete, this may contain a change summary from the site editor.

Verification Code

<?php

if ($_POST['auth'] != 'ENTER YOUR AUTH KEY HERE') {
    die ('Auth key verification failed!');
}

?>

Verifying the Remote Server

if ($_SERVER['REMOTE_ADDR'] != '127.0.0.1') {
	die ('Server verification failed!');
}

if ($_SERVER['REQUEST_METHOD'] != 'POST') {
	die ('Request method verification failed!');
}

A Basic Request Handler

@mail (
    'me@example.com',
    sprintf ('Workflow event notice [%s]', $_POST['event']),
    'Summary: ' . $_POST['summary'],
    'From: noreply@example.com'
);

This example will simply send an email to me@example.com with the event value in the subject line and the summary in the message body whenever an event is triggered.

As you can see, it's easy to implement external callbacks in Sitellite using web hooks. And with a little security precaution as shown above plus a bit of input validation and SSL for encrypted communication, your website and external applications will suddenly start getting along famously.