Table of Contents

Overview

WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST. A web application implementing WebHooks will POST a message to a URL when certain things happen.  You'll need to use an external service, such as a Webhook Integration Service like an Zapier account and the Webhook Service in BloxCMS.

Mobile Applications can interface with BloxCMS by having a Webhook register as a Broadcast Target. The broadcast target would receive the Webhook Call at the appointed time (if delayed) and would be able to do things like a push notification or similar kind of actions. As a generic end-point, other mobile application uses might include notifications for approval of a classified ad or editorial comment, feed updates, etc.


Note:  You do need Admin Permissions to access Webhooks in BloxCMS. See your Site Administrator if you don't have this permission.


For more information on Webhooks, click here.

Setup a Webhook

Once your Webhook Integration Service Provider account is set up, have the URL ready to enter into BloxCMS Admin.


Note:  Some of these Providers do charge to set up an account, some do not. However, most do offer a 14 to 30 day trial period.

Note:  Several of these Providers use email confirmation upon signing up. If the confirmation does not show up in your INBOX, check your SPAM folder.

Note:  For implementation examples, Click Here.


In your BloxCMS Admin, from the dropdown in the the upper left choose Settings / Webhooks (Not sure how to access BLOX Applications? Click here).  This will open the Webhooks window.  You can create a New Webhook, Edit, or Delete one.

+1 
Webhooks_Main.jpg

To Edit, click on the one you wish to edit, then click on Edit, otherwise to create a new one, click on New. This opens the Edit Webhook window.

+1 
Webhooks_New.jpg
  • Copy and Paste the Endpoint URL generated from your Webhook Integration Service Provider into the BloxCMS Admin Webhook you are creating.
  • The Secret (API) key is automatically populated by BloxCMS when you click on New.
  • Select the Events for the Webhook (e.g. Create Article).
  • Click Save.
  • Return to your Webhook Integration Service Provider to finish the setup and test it.

Note:  The Secret Key that is generated will be slightly different for every Webhook you create as it is a Unique Key ID for each specific Webhook on your site.


Webhook Events

EventsOptions
Editorial: Article
  • Create:  First time any Article Assets are saved.
  • Delete:  Removal of Article Assets from the search index and from disk.
  • Update:  Modification to existing Article Assets.
Editorial: Audio
  • Create:  First time any Audio Assets are saved.
  • Delete:  Removal of Audio Assets from the search index and from disk.
  • Update:  Modification to existing Audio Assets.
Editorial: Collection
  • Create:  First time any Collection Assets are saved.
  • Delete:  Removal of Collection Assets from the search index and from disk.
  • Update:  Modification to existing Collection Assets.
Editorial: Flash
  • Create:  First time any Flash Assets are saved.
  • Delete:  Removal of Flash Assets from the search index and from disk.
  • Update:  Modification to existing Flash Assets.
Editorial: HTML
  • Create:  First time any HTML Assets are saved.
  • Delete:  Removal of HTML Assets from the search index and from disk.
  • Update:  Modification to existing HTML Assets.
Editorial: Image
  • Create:  First time any Image Assets are saved.
  • Delete:  Removal of Image Assets from the search index and from disk.
  • Update:  Modification to existing Image Assets.
Editorial: Link
  • Create:  First time any Link Assets are saved.
  • Delete:  Removal of Link Assets from the search index and from disk.
  • Update:  Modification to existing Link Assets.
Editorial: PDF
  • Create:  First time any PDF Assets are saved.
  • Delete:  Removal of PDF Assets from the search index and from disk.
  • Update:  Modification to existing PDF Assets.
Editorial: Poll
  • Create:  First time any Poll Assets are saved.
  • Delete:  Removal of Poll Assets from the search index and from disk.
  • Update:  Modification to existing Poll Assets.
Editorial: Syndicaster
  • Create:  First time any Syndicaster Assets are saved.
  • Delete:  Removal of Syndicaster Assets from the search index and from disk.
  • Update:  Modification to existing Syndicaster Assets.
Editorial: Table
  • Create:  First time any Table Assets are saved.
  • Delete:  Removal of Table Assets from the search index and from disk.
  • Update:  Modification to existing  Assets.
Editorial: Video
  • Create:  First time any  Assets are saved.
  • Delete:  Removal of  Assets from the search index and from disk.
  • Update:  Modification to existing Table Assets.
Editorial: YouTube
  • Create:  First time any YouTube Assets are saved.
  • Delete:  Removal of  Assets from the search index and from disk.
  • Update:  Modification to existing  Assets.
Editorial: Zip
  • Create:  First time any  Assets are saved.
  • Delete:  Removal of YouTube Assets from the search index and from disk.
  • Update:  Modification to existing YouTube Assets.
User: User
  • Create User Account:When a User is created (including pending).
  • Delete User Account:  When a User is deleted from the system.
  • Update User Account:  When a User's Profile is updated.
  • User Login:  When a User is logged in (included "Remember Me").

For Developers

After registering a webhook, events will be delivered to the configured URL with a JSON payload. The format of this payload is:

{
     application: 'application_name',
     event: 'event_name',
     data: { ... }
}

The keys are:

  • application: The application that is sending the message (e.g. editorial, classifieds, etc.)
  • event: The name of the event that is being delivered (e.g. asset_update)
  • data: An event-specific chunk of data that may vary based on the event and application

Additionally, the POST to the end-point will contain a special request header called X-Signature that contains a HMAC digest that can be used to verify that the POST came from the Townnews servers. To verify the signature, the algorithm is:

signature = base64_encode(hash_hmac('sha256', 'JSON payload', 'secret'))

The secret is the secret generated in the BLOX admin when the webhook was created. The JSON payload should be the entire POST body that was delivered.

The data element will consist of action specific keys and can vary by asset type - in the case of editorial actions (update_asset, create_asset, etc.), it will be:

  • uuid: the ID of the asset
  • url: the public URL to the asset
  • title: the title of the asset
  • type: the asset type (e.g. article, image, video, etc.)
  • flags: one or more flags (e.g. ap, breaking_news, etc.)
  • start_time: an ISO-8601 string of the start time of the asset in UTC
  • revision: the revision of the asset - an ever increasing integer starting with 1
  • published: a "yes" or "no" enumeration on whether the asset is live yet or in a draft state

In the case of user events, the payload will contain keys about the user account. The update event for use will contain:

  • id: The unique ID of the user
  • email: The e-mail address of the user
  • screen_name: The screen name of the account
  • first_name: The first name of the user
  • last_name: The last name of the user
  • address: The primary address the user supplied
  • municipality: The primary city/town of the user
  • region: The state or province of the user
  • postal_code: Zip/postal code of the user