スマートフォン用の表示で見る

はてなブックマーク Web Hook

はてな

はてなブックマーク Web Hook

はてなぶっくまーくうぇぶふっく

このページは古い情報を掲載しています

このページの情報は更新されていません。新しい情報は「はてなブックマークWebHook - Hatena Developer Center」に移転しました。

本ドキュメントに関する注意事項

本ドキュメントははてなブックマークにおける Web Hook 機能を解説するものです。主にはてなスタッフがその作成と更新を行っています。

変更履歴

はてなブックマーク Web Hook とは

はてなブックマーク Web Hookはてなブックマーク上でのイベントを他のウェブアプリケーションHTTP で通知する仕組みです。はてなブックマークブックマークを投稿した際、自分のブックマークはてなスターが付与された際、IDコールを受信した場合など各種イベントに合わせて、設定画面で指定した任意の URL に、ブックマーク対象の URL やタイトルなどのデータを HTTP POST します。Web Hook からの HTTP リクエストを受け取るプログラムを用意することで、各イベントに合わせて動作する任意のアプリケーションを開発することができます。

2009年6月3日のリリース時点では、自分のブックマーク投稿イベントのみを扱っていましたが、機能追加により現在以下のイベントに対応しています。

例えば受け取った HTTP リクエスト内容を保存するバックアップアプリケーションや、HTTP リクエストを他のサービスに転送してブックマーク内容を別のサービスに投稿するといったプログラムなどの開発が可能です。

はてなブックマーク Web Hook の利用手順

はてなブックマーク Web Hook は以下の手順で利用できます

  1. はてなブックマークからの HTTP POST リクエストを受け取るプログラムを開発します
  2. 開発したプログラムインターネット上で公開し、URL を割り当てます
  3. プログラムURL を「はてなブックマークの設定画面 > 外部サイト連携 > Web Hook」で設定します (必要であればキーも設定します)
  4. ブックマークを投稿するなど Web Hook に対応したイベントが起こると、指定した URLHTTP リクエストが送られます

はてなブックマーク Web Hook 仕様

Web Hook に対応しているイベント

はてなブックマーク Web Hook は、各イベントに合わせてそのユーザーが設定している URLHTTP POST でパラメータを送信します。以下のイベントに合わせて通知が行われます。括弧内はそのイベントに伴う status パラメータ (後述) の値です。

上記のイベントのうち、アプリケーションが受信するイベントは設定画面から ON/OFF が可能です。

パラメータの仕様

Web Hook が送信する HTTP POST のパラメータの仕様は以下です。

username
ブックマークIDコール、スターを付与したユーザーのid (文字列)
title
イベント対象のエントリのタイトル (文字列)
url
イベント対象のエントリのURL (文字列)
count
イベント対象のエントリの、その時点でのブックマーク数 (整数)
permalink
イベント対象のブックマークパーマリンク
status
イベントの種類。取り得る値は前述のイベントの種類を参照してください。またステータスはアプリケーション側でチェックするようにしてください (後述)
comment
イベント対象のブックマークに付与されたコメント (タグは同梱, 例: "[hatena][bookmark] こんにちは")
timestamp
イベントの時刻 (W3CDTF 形式)
is_private
ブックマークが非公開かどうか (公開 0, 非公開 1 ※はてなブックマークプラスの非公開ブックマークを判別するフラグです)
key
設定したキー (文字列, 後述)

文字エンコーディングUTF-8 です。

ブックマーク追加または更新時に付与されるパラメータ

イベントがブックマーク追加 (status=add) または更新 (status=update) だった場合は、前述のパラメータに加えて以下のパラメータを伴います。

client
ブックマーク追加または更新を行った経路 ('Web', 'AtomAPI', 'Twitter', 'Mail')
はてなスターのイベントだけに付与されるパラメータ

イベントがはてなスター付与 (status=star) だった場合は、前述のパラメータに加えて以下のパラメータを伴います。

color
スターの色 ('yellow' or 'green' or 'blue' or 'red' etc)
quote
はてなスターで引用された文字列 (文字列)

ステータス (status パラメータ) について

はてなブックマーク Web Hook は今後の機能追加により他のイベント通知にも利用する予定です。新しいイベントを追加した際は status パラメータにそのイベントの種類を追加します。アプリケーションを開発するにあたっては、後日追加されるイベントによりアプリケーションが意図しない挙動をしないよう、内部で status のチェックをお願いします。(例えば add / update / delete 以外のステータスだった場合は例外を送出するようにしておく、など)

キーについて

Web Hook からの HTTP リクエストを受け付けるプログラムインターネット上に公開する必要があります。そのため公開した URL を知る第三者がプログラムHTTP リクエストを送信できてしまいます。

プログラム内で、本人ではない第三者からのリクエストを拒否できるよう、はてなブックマーク Web Hook ではキーを利用できます。Web Hook の設定画面でキーに任意の文字列を設定しておくと、その文字列HTTP POST の key パラメータの値として送信します。プログラム側では key パラーメータが確かに設定画面で指定したものと一致しているかを調べることで本人確認が可能です。

キーには特定の文字列ハッシュなど万が一第三者に知られた場合でも二次被害のない文字列を利用されることを推奨します。他サービスで利用している同一のパスワード文字列などは利用しないでください。

サンプルプログラム

はてなブックマーク Web Hook からの HTTP POST リクエストを受け取る perl CGI スクリプトの例を以下に記載します。

#!/usr/bin/env perl
use strict;
use warnings;
use CGI qw/-utf8 :standard/;
use DateTime::Format::W3CDTF;

my $req = CGI->new;

# キーの比較
if ($req->param('key') ne 'xxxxxxxxxxx') {
    die "Authentication failed";
}

# ユーザーの情報
my $username = $req->param('username');

# エントリーの情報
my $url    = $req->param('url');
my $title = $req->param('title');
my $count  = $req->param('count');

# ブックマークの情報
my $status    = $req->param('status'); # 'add' or 'update' or 'delete'
my $timestamp = DateTime::Format::W3CDTF->parse_datetime($req->param('timestamp'));
my $comment     = $req->param('comment');
my $is_private = $req->param('is_private'); # 0 or 1

# ここに好きな処理を実装する

print header('text/plain');
print 'ok';

プログラム開発が終ったらインターネット上に公開し、URL (と必要ならキー) を

の入力欄に登録してください。

ヒント

タグのパース処理

タグはコメントと一緒になっています。タグは perl では以下のコードで分離することができます。

my $comment = "[foo][bar] hogepiyo";
my @tags;

while ($comment =~ m!\[([^\:\[\]]+)\]!g) {
    push @tags, $1;
}

# @tags にタグが入る

デバッグの方法

開発したプログラムの動作確認用に、本仕様と同様のクエリパラメータを POST する HTTP クライアントを記述しておくと便利です。はてなブックマーク上でブックマークの追加作業を行わなくてもデバッグできます。てもデバッグできます。

目次