UnifyPort API key を作成した後に行う最初の Webhook テストチェックリスト

最初の UnifyPort API key を受け取ったら、すぐに messaging account を接続する前にキーを検証してください。安全な順序は、GET /v1/workspace で key を確認し、署名付き webhook endpoint を作成し、message.received または ["*"] を購読し、イベントを保存してから WhatsApp、Telegram、LINE、TikTok、Zalo、X を認可することです。日本向けの LINE 対応でも、この順序は同じです。

要点

• API key は X-Api-Key header で認証します。ブラウザー側コードやリポジトリには入れないでください。
• 新しく作成した key の完全な secret は api_key として一度だけ返ります。後続の list response では key_prefix だけが表示されます。
• 認可の進行状況と inbound message は webhook event として届くため、account 認可より先に webhook を作ります。
• signing_secret を有効にし、raw request body で X-Device-Signature を検証してから payload を信頼します。
• message.received はデモ用ではなく、最初の本番データ契約として扱います。

既存の key を本番で入れ替える場合は、zero-downtime API key rotation runbook を参照してください。最初の inbound architecture を作る段階なら、webhook-first integration checklist と合わせて読むと流れがつかみやすくなります。

1. key がどの workspace に紐づくか確認する

UnifyPort は現在、選定された顧客向けに提供されています。公開ドキュメントでは、workspace access と最初の API key を得るにはチームに連絡するよう案内しています。key を受け取ったら、最初の request は message send ではなく、読み取り専用の workspace check にします。

export UNIFYPORT_API_KEY="set-this-in-your-secret-manager"

curl https://api.unifyport.ai/v1/workspace \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

成功すれば、その key が 1 つの workspace に解決されることが確認できます。Introduction docs では、すべての /v1 endpoint が X-Api-Key request header で認証されること、成功・エラーの JSON response に top-level request_id が含まれることも説明されています。

2. 名前付き key を作り、完全な secret は一度だけ保存する

workspace で追加 key を作成できる場合は、その key を使う runtime が分かる名前にします。たとえば production inbound worker です。Create API key reference によると、key record は key の下に返り、完全な secret は api_key の下に一度だけ返ります。

curl -X POST https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production inbound worker",
    "prefix": "dk_live"
  }'

運用ルールは単純です。返された api_key は secrets manager に直接保存し、issue、チャットログ、client-side environment variable には貼らないでください。OWASP の公式 Secrets Management Cheat Sheet も、API keys を secrets として扱い、作成、保存、rotation、revocation、auditing を 1 つの lifecycle として管理する考え方を示しています。

3. account 接続より先に webhook を登録する

QR、code、session 認可より先に行います。UnifyPort は missed webhook delivery の完全な replay を保証しないため、永続的な inbound record はあなたの receiver と database が持つべきです。

export WEBHOOK_SIGNING_SECRET="generate-a-long-random-secret"

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://inbox.example.com/unifyport/webhook",
    "status": "active",
    "subscribed_events": ["message.received"],
    "signing_secret": "'"$WEBHOOK_SIGNING_SECRET"'"
  }'

Create webhook endpoint reference では、公開 standard event name を正確に指定する方法と、["*"] で全公開 standard events を購読する方法が説明されています。account state machine 全体を作るなら ["*"]、LINE などの inbound message をまず受けたいだけなら message.received から始めるのが確認しやすいです。

4. raw body で webhook signature を検証する

Delivery docs は X-Device-Event-Id、X-Device-Delivery-Id、X-Device-Timestamp、X-Device-Signature を定義しています。signature は次の値の hex-encoded HMAC-SHA256 です。

<X-Device-Timestamp> + "." + <raw request body>

重要なのは raw body です。framework が先に JSON を parse し、再度 serialize すると byte sequence が変わり、signature verification が失敗することがあります。

import crypto from 'crypto';
import express from 'express';

const app = express();
const signingSecret = process.env.WEBHOOK_SIGNING_SECRET;

app.post('/unifyport/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Device-Timestamp') || '';
  const signature = req.get('X-Device-Signature') || '';

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(timestamp + '.')
    .update(req.body)
    .digest('hex');

  const valid = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  if (!valid) return res.status(401).end();

  const event = JSON.parse(req.body.toString('utf8'));
  if (event.type === 'message.received') {
    console.log(event.provider, event.data.conversation.id, event.data.message.text);
  }

  res.status(200).end();
});

詳細は Webhook delivery & signature verification にあります。retry、idempotency、stale timestamp check、任意の 2xx response が delivery acknowledgement になるルールもここで確認できます。

5. message.received envelope を最初の contract として保存する

通常の inbound message は、id、type、provider、account_id、occurred_at、data という安定した envelope を持ちます。standard event payload reference は、実装で依存すべき field を示しています。

{
  "id": "evt_2f9c1a4b7e",
  "type": "message.received",
  "provider": "line",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:34:56Z",
  "data": {
    "conversation": { "id": "u1234567890", "type": "user" },
    "sender": { "id": "u1234567890", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "msg_10472",
      "text": "配送状況を確認したいです",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:34:55Z"
    }
  }
}

top-level event id は idempotency、provider と account_id は routing、data.conversation.id は queue grouping、data.sender.id は identity、data.message.id は message-level action のために保存します。この形が固まれば、同じ receiver で LINE を先に受け、後から WhatsApp、Telegram、Zalo、TikTok、X を追加できます。AI coding agent で同じ流れを実装する例は、AI coding agent auto-reply bot tutorial を参照してください。

初日に起きやすいミス

ミス	影響	安全な対応
account を先に作り、webhook を後にする	認可 event が receiver 作成前に届くことがある	先に webhook endpoint を作る
signing を無効にする	URL を知っている相手が似た JSON を送れる状態になる	signing_secret を設定し、raw-body HMAC を検証する
delivery attempt だけで重複排除する	retry で同じ event が複数回届く	X-Device-Event-Id または event id で idempotent に処理する
API key を log に出す	secret が監査しにくい場所へ広がる	secrets manager に保存し、log では redaction する
message.received を WhatsApp 専用と考える	実際には対応 provider 横断の normalized event	provider と account field を保存し、単一 platform 前提にしない

FAQ

完全な API key を後から取得できますか？

いいえ。作成 response では完全な secret が api_key として一度だけ返ります。list や detail response では key_prefix など表示用 metadata だけが返ります。

message.received と ["*"] のどちらを購読すべきですか？

最初の inbound test だけなら message.received です。auth、runtime、message、receipt、conversation、group event まで 1 つの receiver で扱うなら ["*"] を使います。

account 作成前に webhook endpoint は必要ですか？

信頼できる初回テストには必要です。account authorization の進行状況と live inbound messages は webhook event として届き、UnifyPort は missed payload の完全な replay を約束しません。

すべての platform で公式 business account が必要ですか？

いいえ。UnifyPort は WhatsApp、Telegram、LINE、TikTok、Zalo、X 向けの unofficial interface を提供し、用途に合う場合は personal または ordinary messaging account を接続できます。

次のステップ

Quickstart を開き、API key を secrets manager に入れ、webhook endpoint を先に作成してから delivery verification docs に沿って receiver を実装してください。

Sources checked on 2026-09-01

• UnifyPort Create API key reference
• UnifyPort Create webhook endpoint reference
• UnifyPort Webhook delivery & signature verification
• OWASP Secrets Management Cheat Sheet