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.

The process for checking the signature is:

  1. Get (or set) a secret for the webhook in Flockler
  2. Receive a webhook HTTP request from us
  3. Collect HTTP verb, webhook action, environment, webhook URL, and the payload
  4. Create the string to sign
  5. Sign the string with HMAC-SHA256 using the webhook's secret
  6. Convert to base64 hex
  7. Compare the base64 hex you just created to the request's X-Flockler-Signature. If it does not match, you should _not_ trust the request!

Pattern for string to sign is http_verb|action|env|webhook_url|payload. The string has to be in lowercase before signing. Below you can find a table with descriptions for each individual field.

Field Description
http_verb Request's HTTP method/verb (usually POST).
action Request's X-Flockler-Action header.
env Request's X-Flockler-Env header.
webhook_url The URL of the webhook as it was added to Flockler. With whitespaces and everything.
payload Request's raw payload. NOTE: Make sure you do not parse they payload e.g. with http-parser. It has to be the raw HTTP request payload.

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

Example of a 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.

Q: I'm having trouble generating a valid signature

Please make sure you are using the raw HTTP payload, that the webhook URL is 1-to-1 as it's been typed into Flockler, and that the lowercase conversion is not ignoring/malforming UTF-8 characters such as Ä, Ö or Å.

Q: I'm getting duplicate articles

You should make sure that if you get two simultaneous requests, the other one is locked (mutex) until it is done, so you don't create duplicates. Typically when you create an article we immediatelly do some background processing – such as cache external images – which might be finished very quickly and result in two webhook requests firing within milliseconds from each other.

Q: I receive requests that look 100% identical to data I already have

We do a lot of background processing for our articles, such as caching Instagram profile photos, clearing Facebook OG cache, checking if the content has been removed, etc. These operations usually trigger an "update" action just to be safe.