はてなブックマーク Web Hook

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

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

変更履歴

• 2009年6月3日 リリース
• 2009年6月12日 IDコール、はてなスター、お気に入りのブックマークのイベントについて加筆
• 2009年11月12日 client パラメータの追加について加筆
• 2009年12月24日 client パラメータに Mail を追加

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

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

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

• 自分がブックマークしたというイベント
• 自分のブックマークに第三者からはてなスターが付与されたというイベント
• 自分に対して第三者からはてなブックマークのコメントで ID コールが送信されたというイベント
• 自分がお気に入りに入れている(公開設定の)ユーザーが新規に(公開設定で)ブックマークしたというイベント

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

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

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

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

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

ステータス (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 (と必要ならキー) を

• はてなブックマークの設定画面 > 外部サイト連携 > Web Hook

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

ヒント

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

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

# @tags にタグが入る