A 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 BLOX CMS.

Mobile Applications can interface with BLOX 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.

Webhook Integration Service Providers

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.

How to add a new Webhook

To add a new Webhook, within the Webhook panel, select + New. 

Within the Edit Webhook panel, enter the the URL (or Endpoint URL) that was created/generated from the Webhook Integration Service Provider. This is the URL that will be POSTed to when the selected events occur.  

A Secret for the Webhook will automatically be created upon the creation of a new Webhook. 

Lastly, select the Events that the Webhook should be listening to. Use the + option for each Event to explore all of the available listening capabilities.

Webhooks may be edited or removed by utilizing either toolbar option.

Webhook Events

Developer Information

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-Hook-Signature that contains a HMAC digest that can be used to verify that the POST came from the BLOX Digital 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