Webhook 事件

Piora Webhook 讓你可以在特定事件發生時，接收即時的 HTTP 通知。你可以利用 Webhook 整合 Slack 通知、觸發下游流程、或建立自訂的自動化工作流程。

設定 Webhook

建立 Webhook

進入「設定」>「Webhook」
點選「新增 Webhook」
設定以下參數：

參數	說明	範例
URL	接收通知的端點	`https://your-server.com/webhook`
事件	要監聽的事件類型	選擇一個或多個
Secret	簽名密鑰（用於驗證）	自動產生或自訂
狀態	啟用或停用	啟用

事件類型

部署事件

事件	說明
`deployment.started`	部署開始
`deployment.succeeded`	部署成功
`deployment.failed`	部署失敗
`deployment.rolled_back`	部署回滾

應用事件

事件	說明
`application.created`	應用建立
`application.deleted`	應用刪除
`application.started`	應用啟動
`application.stopped`	應用停止
`application.crashed`	應用異常退出

伺服器事件

事件	說明
`server.connected`	伺服器連線成功
`server.disconnected`	伺服器連線中斷
`server.alert`	伺服器告警（CPU、記憶體等）

資料庫事件

事件	說明
`database.created`	資料庫建立
`database.deleted`	資料庫刪除
`backup.completed`	備份完成
`backup.failed`	備份失敗

Webhook 負載格式

每個 Webhook 請求都是 POST 方法，包含 JSON 負載：

{
  "event": "deployment.succeeded",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "application": {
      "id": "app_xxxxxxxxxxxx",
      "name": "my-web-app"
    },
    "deployment": {
      "id": "deploy_xxxxxxxxxxxx",
      "status": "succeeded",
      "commit": "abc1234",
      "branch": "main",
      "duration": 45
    },
    "server": {
      "id": "srv_xxxxxxxxxxxx",
      "name": "production"
    }
  }
}

簽名驗證

每個 Webhook 請求都包含簽名標頭，讓你驗證請求確實來自 Piora：

X-Piora-Signature: sha256=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

驗證範例

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express.js 範例
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-piora-signature'];
  if (!verifyWebhook(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // 處理事件...
  res.status(200).send('OK');
});

重試機制

如果你的 Webhook 端點回傳非 2xx 狀態碼，Piora 會自動重試：

重試次數	等待時間
第 1 次	1 分鐘後
第 2 次	5 分鐘後
第 3 次	30 分鐘後
第 4 次	2 小時後
第 5 次	12 小時後

超過 5 次重試後，該事件將被標記為失敗。

Webhook 日誌

在控制面板中可以查看每個 Webhook 的發送記錄：

發送時間
事件類型
HTTP 狀態碼
回應時間
負載內容
重試記錄