ຮັບໂພສຈາກ Orova Social ຜ່ານ Webhook

/ ພາບລວມ

ຫຼັກການເຮັດວຽກ

ທ່ານລະບຸທີ່ຢູ່ຮັບຂໍ້ມູນ (https://) ແລະ ລະຫັດລັບໄວ້ທີ່ຊ່ອງທາງ API ຂອງໂຄງການ. Orova ຈະສົ່ງ request POST ພ້ອມເນື້ອໃນເປັນ JSON ໄປທີ່ນັ້ນ ແລະ ແນບສ່ວນຫົວ X-Orova-Signature ເຊິ່ງແມ່ນ HMAC-SHA256 ຂອງໄບຕ໌ດິບຂອງເນື້ອໃນນັ້ນ ໂດຍໃຊ້ລະຫັດລັບຂອງທ່ານ. endpoint ຂອງທ່ານກວດລາຍເຊັນ, ຮັບໂພສ, ແລ້ວຕອບກັບດ້ວຍລະຫັດ 2xx.

• ທີ່ຢູ່ຮັບຂໍ້ມູນຕ້ອງເປັນ https. ຖ້າທີ່ຢູ່ບໍ່ແມ່ນ https:// ຫຼື ບໍ່ມີຊື່ໂຮສ, Orova ຈະບໍ່ບັນທຶກຊ່ອງທາງ ແລະ ແຈ້ງລະຫັດ api_url.
• ໜຶ່ງທີ່ຢູ່ ໜຶ່ງຊ່ອງທາງ. Orova ໃຊ້ທີ່ຢູ່ຮັບຂໍ້ມູນເປັນຕົວລະບຸຊ່ອງທາງ. ບັນທຶກທີ່ຢູ່ເກົ່າຊ້ຳແມ່ນການຂຽນທັບຊ່ອງທາງເດີມ, ບໍ່ສ້າງຊ່ອງທາງຊ້ຳ.
• ມີປຸ່ມສົ່ງທົດລອງ. ເມື່ອເຊື່ອມແລ້ວ ຊ່ອງທາງຈະມີປຸ່ມ Send test: Orova ຍິງຂໍ້ມູນ orova.test ໄປຫາ endpoint ຂອງທ່ານທັນທີ ແລ້ວສະແດງລະຫັດ HTTP ທີ່ໄດ້ຮັບ ພ້ອມເວລາໄປ-ກັບເປັນມິນລິວິນາທີ.

/ ຕັ້ງຄ່າ

ຕັ້ງຄ່າໃນ Orova

ເປີດ Social → ໂຄງການ → ເລືອກໂຄງການ → ແທັບ ຊ່ອງທາງ ແລ້ວຫາກ່ອງ API. ໃນນັ້ນມີຊ່ອງປ້ອນສອງຊ່ອງ ແລະ ປຸ່ມໜຶ່ງປຸ່ມ.

• 1

  URL ຮັບຂໍ້ມູນ (webhook). ທີ່ຢູ່ endpoint ຂອງທ່ານ ຂຶ້ນຕົ້ນດ້ວຍ https://. ທຸກ request ຈະຖືກສົ່ງມາທີ່ນີ້.

• 2

  ລະຫັດລັບ. ສະຕຣິງທີ່ໃຊ້ເຊັນ. ຖ້າປະວ່າງ Orova ຈະສຸ່ມໃຫ້ ແຕ່ໜ້າຈໍຈະບໍ່ສະແດງຄືນ, ດັ່ງນັ້ນຄວນສ້າງສະຕຣິງຍາວເອງແລ້ວວາງໃສ່ ແລະ ເກັບສຳເນົາໄວ້ຝ່າຍທ່ານ.

• 3

  ກົດ Save channel. ຊ່ອງທາງຈະປາກົດໃນລາຍການພ້ອມທີ່ຢູ່ຮັບຂໍ້ມູນ. ລະຫັດລັບຈະບໍ່ສະແດງອີກ.

• 4

  ກົດ Send test. Orova ຈະສົ່ງຂໍ້ມູນຕົວຢ່າງ orova.test. ຖ້າ endpoint ຕອບ 2xx Orova ຈະແຈ້ງວ່າ “Webhook ຕອບ 200 ໃນ … ms”. ລະຫັດອື່ນຈະແຈ້ງພ້ອມລະຫັດນັ້ນ; ຕິດຕໍ່ບໍ່ໄດ້ຈະແຈ້ງເປັນຂໍ້ຜິດພາດເຄືອຂ່າຍ.

/ ຂໍ້ຕົກລົງ

ຂໍ້ຕົກລົງຂອງ request

ທຸກເທື່ອທີ່ສົ່ງ, request ຈະມີໜ້າຕາແບບນີ້:

POST <your receiving URL>

Headers:
  Content-Type: application/json
  X-Orova-Signature: sha256=<hex HMAC-SHA256 of the raw body>
  X-Orova-Event: orova.test
  User-Agent: Orova-Social/1.0

Body (JSON):
  {
    "event": "orova.test",
    "workspace_id": 12,
    "project_id": 34,
    "post": {
      "title": "...",
      "content": "...",
      "media": [],
      "channels": ["api"]
    },
    "sent_at": "2026-08-23T01:25:00Z"
  }

ເນື້ອໃນເປັນ JSON UTF-8 ແບບກະທັດຮັດ ແຖວດຽວ. ໃຫ້ອ່ານຄ່າ event ເພື່ອແຍກປະເພດ — ຂໍ້ມູນຈາກປຸ່ມສົ່ງທົດລອງມີຄ່າ orova.test ແລະ ສ່ວນຫົວ X-Orova-Event ກໍ່ເປັນຄ່າດຽວກັນ. endpoint ຂອງທ່ານຄວນຂ້າມຊ່ອງຂໍ້ມູນທີ່ບໍ່ຮູ້ຈັກ ແທນທີ່ຈະປະຕິເສດ, ເພື່ອໃຫ້ການເພີ່ມຊ່ອງໃນອະນາຄົດບໍ່ເຮັດໃຫ້ລະບົບທ່ານພັງ.

/ ການກວດສອບ

ກວດລາຍເຊັນ

ສ່ວນຫົວ X-Orova-Signature ຢູ່ໃນຮູບ sha256=<hex> ໂດຍ <hex> ແມ່ນ HMAC-SHA256 ຂອງໄບຕ໌ດິບຂອງເນື້ອໃນ request ໃຊ້ລະຫັດລັບຂອງຊ່ອງທາງ. ໃຫ້ຄິດໄລ່ຄືນຈາກໄບຕ໌ທີ່ໄດ້ຮັບໂດຍກົງ — ຖ້າແປງ JSON ແລ້ວສ້າງສະຕຣິງໃໝ່ຈະບໍ່ກົງ, ເພາະຕ່າງກັນພຽງຊ່ອງວ່າງດຽວລາຍເຊັນກໍ່ປ່ຽນ.

Node.js

// Node.js / Express — verify X-Orova-Signature, then answer fast
import express from "express";
import crypto from "node:crypto";

const app = express();
const OROVA_SECRET = process.env.OROVA_SECRET;   // the key you saved in Orova

// Keep the RAW bytes: the signature covers them, not re-serialized JSON.
app.post(
  "/orova/social",
  express.raw({ type: "application/json", limit: "5mb" }),
  (req, res) => {
    const sent = req.get("x-orova-signature") || "";
    const mine =
      "sha256=" +
      crypto.createHmac("sha256", OROVA_SECRET).update(req.body).digest("hex");

    // Constant-time compare — never use ===.
    const a = Buffer.from(sent);
    const b = Buffer.from(mine);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).json({ error: "bad signature" });
    }

    const payload = JSON.parse(req.body.toString("utf8"));
    if (payload.event === "orova.test") {
      return res.status(200).json({ ok: true });   // the Send test button
    }

    // Real post: hand the work to a queue and reply straight away.
    queuePost(payload).catch(console.error);
    return res.status(200).json({ ok: true });
  },
);

app.listen(3000);

Python

# Python / Flask — same check, same rules
import hashlib
import hmac
import json
import os

from flask import Flask, request

app = Flask(__name__)
OROVA_SECRET = os.environ["OROVA_SECRET"].encode("utf-8")

@app.post("/orova/social")
def orova_social():
    raw = request.get_data()                       # bytes, exactly as sent
    mine = "sha256=" + hmac.new(OROVA_SECRET, raw, hashlib.sha256).hexdigest()
    sent = request.headers.get("X-Orova-Signature", "")
    if not hmac.compare_digest(mine, sent):        # constant-time compare
        return {"error": "bad signature"}, 401

    payload = json.loads(raw)
    if payload.get("event") == "orova.test":
        return {"ok": True}, 200

    queue_post(payload)                            # do the slow work later
    return {"ok": True}, 200

ປຽບທຽບດ້ວຍຟັງຊັນແບບເວລາຄົງທີ່ (crypto.timingSafeEqual, hmac.compare_digest), ຢ່າໃຊ້ການທຽບເທົ່າທຳມະດາ. ຖ້າລາຍເຊັນບໍ່ກົງໃຫ້ຕອບ 401 ແລ້ວຢຸດ — ຢ່າປະມວນຜົນຂໍ້ມູນນັ້ນ.

/ ການຕອບກັບ

ຕອບກັບແນວໃດ

Orova ເບິ່ງສະເພາະລະຫັດສະຖານະ HTTP. ລະຫັດໃນກຸ່ມ 2xx ຖືວ່າສຳເລັດ; ເນື້ອໃນທີ່ຕອບກັບຈະເປັນຫຍັງກໍ່ໄດ້.

• ຕອບໃຫ້ໄວ. ປຸ່ມສົ່ງທົດລອງລໍຖ້າບໍ່ເກີນ 10 ວິນາທີ. ວຽກໜັກ ເຊັ່ນ ດາວໂຫຼດໄຟລ໌ສື່ ຫຼື ເອີ້ນ API ພາຍນອກ ໃຫ້ໂຍນເຂົ້າຄິວແລ້ວຕອບ 2xx ທັນທີ.
• Orova ບໍ່ລອງສົ່ງຊ້ຳເອງ. ນີ້ແມ່ນເຈດຕະນາ: ການລອງສົ່ງຊ້ຳອັດຕະໂນມັດກັບ API ເຜີຍແຜ່ແມ່ນຕົ້ນເຫດຂອງການໂພສສອງເທື່ອ. ເມື່ອສົ່ງບໍ່ສຳເລັດ ໂພສຈະຖືກໝາຍເປັນ failed ພ້ອມເຫດຜົນ ແລ້ວຜູ້ໃຊ້ກົດເຜີຍແຜ່ຄືນໃນ Orova.
• ຮອງຮັບຂໍ້ມູນຊ້ຳໄດ້. ເມື່ອຜູ້ໃຊ້ກົດເຜີຍແຜ່ຄືນ ຂໍ້ມູນຊຸດເກົ່າຈະມາອີກເທື່ອ. ໃຫ້ກັ່ນຕອງຊ້ຳຢູ່ຝ່າຍທ່ານ ເຊັ່ນ ຈື່ຄູ່ workspace_id ກັບ sent_at ທີ່ຈັດການໄປແລ້ວ.

/ ຄວາມປອດໄພ

ຄວາມປອດໄພ

• ກວດລາຍເຊັນສະເໝີ. endpoint ຂອງທ່ານເປັນ URL ສາທາລະນະ ໃຜກໍ່ເອີ້ນໄດ້. ລາຍເຊັນແມ່ນສິ່ງດຽວທີ່ຢືນຢັນວ່າຂໍ້ມູນມາຈາກ Orova ແທ້.
• ຢ່າເກັບລະຫັດລັບໄວ້ໃນໂຄ້ດ. ເກັບໄວ້ໃນຕົວແປສະພາບແວດລ້ອມ ຫຼື ລະບົບຈັດການຄວາມລັບ, ຢ່າຂຽນຕາຍຕົວລົງໄຟລ໌ທີ່ທ່ານ commit.
• ປ່ຽນລະຫັດດ້ວຍການບັນທຶກຄືນ. ປ້ອນທີ່ຢູ່ຮັບຂໍ້ມູນເກົ່າພ້ອມລະຫັດໃໝ່ແລ້ວກົດ Save channel — Orova ຈະຂຽນທັບຊ່ອງທາງເດີມ. ຢ່າລືມອັບເດດຝ່າຍ endpoint ໄປພ້ອມກັນ.
• ຕັດການເຊື່ອມຕໍ່ຄືການລຶບລະຫັດ. ເມື່ອທ່ານຕັດການເຊື່ອມຕໍ່ຊ່ອງທາງ Orova ຈະລຶບລະຫັດລັບທີ່ເກັບໄວ້ ແລະ ຢຸດສົ່ງຂໍ້ມູນໄປທີ່ຢູ່ນັ້ນ.

/ ສະຫຼຸບ

ຂໍ້ຕົກລົງມີເທົ່ານີ້

ທີ່ຢູ່ https ໜຶ່ງບ່ອນ, ລະຫັດລັບໜຶ່ງອັນ, ກວດລາຍເຊັນໜຶ່ງເທື່ອ ແລະ ລະຫັດ 2xx ໜຶ່ງລະຫັດ — ເທົ່ານີ້ໂພສຈາກ Orova Social ກໍ່ໄຫຼເຂົ້າລະບົບຂອງທ່ານ. ສ່ວນທີ່ເຫຼືອ — ຈະເຜີຍແຜ່ຕໍ່ບ່ອນໃດ, ເກັບໄວ້ໃສ, ບັນທຶກແນວໃດ — ທ່ານເປັນຜູ້ກຳນົດ.