Webhooks

Webhooks allow external services to be notified when certain events happen in Flockler. Currently, we only send notifications for article events. These notifications are sent over HTTP/HTTPS as a POST request.

Every request will contain some special headers and a JSON payload.

Please contact our team at team@flockler.com if you want to register a webhook for a Flockler site or section.

Example payload

Here's an example payload sent by the webhook. The individual parts of the payload are discussed below.

POST /notify HTTP/1.1

Host: localhost:1234
Accept: */*
Content-Type: application/json; charset=utf-8
User-Agent: FL-Webhook
X-Flockler-Action: update
X-Flockler-Env: development
X-Flockler-Signature: d9ed2bc9dda9f12ae164c810802e1e07236408fdefd4e25fdd7e3848e91d3e4e
Content-Length: 9012

{
    "action": "update",
    "article": {
        "id": 702920,
        "article_url": "writing-fast-ruby-by-erik-michaels-ober",
        "author": "ajk",
        "body": "<p>Good tips for optimizing your Ruby code. Remeber though, premature optimization is the root of all evil!</p>\n",
        "cover_pos_x": 50,
        "cover_pos_y": 0,
        "cover_url": "https://flockler.com/thumbs/8496/magenta_s600x0_q80_noupscale.png",
        "display_style": "article",
        "pinned_index": null,
        "order_number": 12,
        "published_at": "2014-11-24T22:00:00Z",
        "published_at_l10n": "2014-11-24T00:00:00+02:00",
        "section_id": 718,
        "site_id": 180,
        "site_pinned_index": null,
        "site_order_number": 12,
        "source_url": null,
        "summary": "",
        "tags": ["ruby", "optimization"],
        "title": "Writing Fast Ruby by Erik Michaels-Ober",
        "type": "link",
        "url": "http://flockler.com/ajk/blog/writing-fast-ruby-by-erik-michaels-ober",
        "attachments": { }
    }
}

Headers

Every notification will contain these special headers:

Name Description
X-Flockler-Action The action which triggered this notification. See X-Flockler-Action section below.
X-Flockler-Env Environment from where this notification was sent. You should only accept notifications from production. Values: development, sandbox, staging, production
X-Flockler-Signature HMAC hex signature of the payload using the webhook's secret as the key. See signature section below.

Actions

These are the article actions that are include in the X-Flockler-Action header which currently trigger a notification. The action is included in both the X-Flockler-Action and in the actual JSON payload. You can use the header to easily filter the request you want to process.

Name Description
publish Article was published.
update Article was updated.
unpublish Article was unpublished. Contains only the ID of article which was unpublished.

Signature

Every webhook request sent from Flockler's servers contains a X-Flockler-Signature header to check the requests authenticity. You should definitely check the signature for each request you receive.

String to sign can be formed based on the request. The string to sign is then signed with HMAC-SHA256 using the webhook's secret and converted to base64 hex. Patten for string to sign is http_verb|action|env|webhook_url|payload. The string has to be converted to lowercase before HMAC-SHA256.

Field Description
http_verb Request's HTTP method/verb (usually POST).
action The value of X-Flockler-Action header.
env The value of X-Flockler-Env header.
webhook_url The URL of the webhook as it was given to Flockler.
payload The payload of the HTTP request.

Note! All these fields need to be converted to lowercase before doing HMAC-SHA256.

Example of string to sign:

post|publish|development|http://localhost:1234/|{"action":"publish","article":{"id":1604729,"article_url":"test","author":"ajk","body":"testing\n","published_at":"2015-10-16T00:45:58Z","section_id":1,"site_id":1,"title":"test","type":"article","url":"http://flockler.dev:3000/ajk/dump/test"}}

Sample snippets for checking the signature:

Support

If you have any questions, don't hesitate to contact our team at team@flockler.com.