Asana で Webhook を登録する方法

仕事で使う技術的なこと

Asana → Webhook でタスク追加を通知 → AWS Lambda → 社内システムへ通知

というのを実現しようとしているのですが、そもそもの Asana の Webhook 登録にかなりてこずりましたので、備忘録します。

前提

いろいろやってみてわかったのですが、Asana の仕様として、まず「Webhookを登録する（作成する）」という概念があるみたいです。

Webhook 自体は複数作ることができますが、１つの Webhook には GID とよばれるユニークなIDが振られ、GIDを使用することで、既存の Webhook に機能を追加したり、Webhook 自体を削除することができます。

なお、おそらくですが Webhook １つに対して１つのアクセストークンを消費する仕組みです。
なので複数のWebhookを作るためには、その分だけアクセストークンを用意する必要があります。

今回の目標

  • Lambda で Webhook エンドポイントを作成し、Webhook を１つ登録する

→ Webhook で具体的に何かしらのアクション処理するところまでは、本記事では扱いません

大まかな手順

  1. Asana 側で、Webhook を使用するためのアクセストークンを作成する
  2. Lambda で Webhook のエンドポイントを作成する
  3. curl を使って、Asana に Webhook を登録する

詳細な手順

1. Asana 側で、Webhook を使用するためのアクセストークンを作成する

  • あらかじめ Asana にログインしておきます
  • https://app.asana.com/0/developer-console を開きます
  • 「個人アクセストークン」の「トークンを新規作成」を押します
  • ポップアップが表示されるので、トークン名を入力します
  • トークンが生成されます。トークンをコピーして、メモ帳とか何かに保管します
    • トークンはここで保管しておかないと、もう確認できなくなります
      • トークンは 1/0000000000000/xxxxxxxxxxxxxx みたいな形式です

2. Lambda で Webhook のエンドポイントを作成する

  • AWS の Lambda で関数を新規作成します
  • ランタイムは「Node.js」を選択し、「詳細設定」を選択します
  • タブが展開されるので、「関数URLを有効化」にチェックを入れ、認証タイプを「NONE」にします
  • そのまま関数を作成します
  • コードソースには、以下のような記載をします
    • Webhook によって Post されたデータから x-hook-secret の値を返す処理
    • Asana の Webhook の仕様で、x-hook-secret が返されると、登録が完了される
export async function handler(event) {
  // x-hook-secret の値をログに残す
  console.log('x-hook-secret:' + event.headers['x-hook-secret'])

  // x-hook-secret の値を返す
  const response = {
    statusCode: 200,
    headers: {"x-hook-secret": event.headers['x-hook-secret']},
  };
  return response;
}
  • 「Deploy」を押して、エンドポイントとしてデプロイする
  • エンドポイントのURLを保存しておきます

3. curl を使って、Asana に Webhook を登録する

  • 対象のプロジェクトIDを控える
    • Webhook はプロジェクトごとに登録する仕様のようです
    • Asana でプロジェクトを開いた時のURLである https://app.asana.com/0/xxxxxxxx の xxxxxxxx にがいとうするのがプロジェクトIDです
  • 以下の通りで、curl を実行します。
curl -X POST https://app.asana.com/api/1.0/webhooks \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {アクセストークン}' \
  -d '{
  "data": {
    "filters": [
      {
        "action": "added",
        "resource_type": "task"
      }
    ],
    "resource": {プロジェクトのID},
    "target": {Webhook のエンドポイントとなる URL}
  }
}'
  • 実行して成功すると、以下のような応答が返ってきます
{
  "data": {
    "gid": "xxxxxxx",
    "resource_type": "webhook",
    "resource": {
      "gid": "{プロジェクトID}",
      "resource_type": "project",
      "name": "{プロジェクト名}"
    },
    "target": "{Webhook のエンドポイントとなる URL}",
    "active": true,
    "is_workspace_webhook": false,
    "created_at": "2023-07-20T12:20:00.564Z",
    "last_failure_at": null,
    "last_failure_content": "",
    "last_success_at": "2023-07-20T12:20:01.720Z",
    "filters": [
      {
        "resource_type": "task",
        "resource_subtype": null,
        "action": "added",
        "fields": null
      }
    ]
  }
}
  • 上記において、 data.gid （xxxxxxxxに該当するところ）が WebhookをユニークにするIDとなります。これを忘れるとたぶんWebhookが削除できなくなると思うので、メモ帳等に忘れずに控えておきます。
  • また、Webhook を今後使用するにあたり、エンドポイント側で取得した x-hook-secret の値も重要になります。
    CloudWatch Logs にログが出力されているので控えておきます。

おまけ：Webhookの削除方法

作成済みの Webhook を削除する方法は以下をcurlします。

curl --request DELETE \
     --url https://app.asana.com/api/1.0/webhooks/{WebhookのGID} \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {アクセストークン}'

ここで Webhook の GID が必要となります。

ちなみに、下記サイトからも Webhook 関連の処理をブラウザから実行できるのでお勧めです。

Delete a webhook
This method permanently removes a webhook. Note that it may be possible to receive a request that was already in flight after deleting the webhook, but no furth...
developers.asana.com

コメント

タイトルとURLをコピーしました