Lưu tài liệu và callback

POST /o3o/callback HTTP/1.1
Host: app.example.com
Content-Type: application/json; charset=utf-8
User-Agent: O3O-Gate/1.0
X-O3O-Event: document.saved
X-O3O-Delivery: 6f1c2b7e-2d0a-4c61-9a57-0f3b1c8d9e21
X-O3O-Timestamp: 1790086400
X-O3O-Signature: sha256=<hex HMAC_SHA256(O3O_EMBED_CALLBACK_SECRET, "1790086400." + thân nguyên văn)>

{"status": "saved", "key": "hopdong-42-v7", "version": 3, ...}

{
  "status": "saved",
  "key": "hopdong-42-v7",
  "version": 3,
  "url": "http://localhost:8080/o3o/embed/files/doc_9835f61009fc659dfedab8696f2d2665?v=3&exp=1790086400&sig=5f1c…",
  "fileType": "docx",
  "title": "Hợp đồng mẫu.docx",
  "size": 48890,
  "sha256": "b1946ac92492d2347c6235b4d2611184…",
  "users": [
    {
      "id": "u-1001",
      "name": "Nguyễn Văn A"
    },
    {
      "id": "u-1002",
      "name": "Trần Thị B"
    }
  ],
  "savedBy": {
    "id": "u-1001",
    "name": "Nguyễn Văn A"
  },
  "autosave": false,
  "final": false,
  "modifiedByUser": true,
  "timestamp": "2026-09-21T10:05:00Z"
}

{
  "status": "closed",
  "key": "hopdong-42-v7",
  "version": 4,
  "url": "http://localhost:8080/o3o/embed/files/doc_9835f61009fc659dfedab8696f2d2665?v=4&exp=1790090000&sig=9a0e…",
  "fileType": "docx",
  "title": "Hợp đồng mẫu.docx",
  "size": 49102,
  "sha256": "7d865e959b2466918c9863afca942d0f…",
  "users": [],
  "savedBy": null,
  "autosave": false,
  "final": false,
  "modifiedByUser": false,
  "timestamp": "2026-09-21T10:31:00Z"
}

// npm install express
const crypto = require("crypto");
const express = require("express");

// rawBody là Buffer của thân yêu cầu NGUYÊN VĂN, chưa phân tích JSON
function verifyO3OSignature(secret, timestamp, rawBody, signature, toleranceSeconds = 300) {
  const ts = Number(timestamp);
  if (!signature || !Number.isInteger(ts)) return false;
  if (Math.abs(Date.now() / 1000 - ts) > toleranceSeconds) return false;
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(String(signature));
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();
// express.raw giữ thân dạng Buffer; đừng để express.json() chạy trước route này
app.post("/o3o/callback", express.raw({ type: "*/*", limit: "1mb" }), (req, res) => {
  const ok = verifyO3OSignature(process.env.O3O_EMBED_CALLBACK_SECRET, req.get("X-O3O-Timestamp"), req.body, req.get("X-O3O-Signature"));
  if (!ok) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(204);                                   // trả lời trong 10 giây, việc nặng làm sau
  console.log(req.get("X-O3O-Delivery"), event.status, event.key, event.version);
});
app.listen(3000);

module.exports = { verifyO3OSignature };

<?php
// PHP thuần; trong Laravel dùng $request->getContent() và $request->header(...)
function verify_o3o_signature(string $secret, string $timestamp, string $rawBody, string $signature, int $tolerance = 300): bool
{
    if ($signature === '' || !ctype_digit($timestamp)) {
        return false;
    }
    if (abs(time() - (int) $timestamp) > $tolerance) {
        return false;
    }
    $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    return hash_equals($expected, $signature);
}

$raw = file_get_contents('php://input');                // thân nguyên văn
$ok = verify_o3o_signature(
    getenv('O3O_EMBED_CALLBACK_SECRET') ?: '',
    $_SERVER['HTTP_X_O3O_TIMESTAMP'] ?? '',
    $raw,
    $_SERVER['HTTP_X_O3O_SIGNATURE'] ?? ''
);
if (!$ok) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
error_log(($_SERVER['HTTP_X_O3O_DELIVERY'] ?? '') . ' ' . $event['status'] . ' v' . $event['version']);
http_response_code(204);

# pip install flask
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request


def verify_o3o_signature(secret: str, timestamp: str, raw_body: bytes, signature: str, tolerance: int = 300) -> bool:
    if not signature or not timestamp.isdigit():
        return False
    if abs(time.time() - int(timestamp)) > tolerance:
        return False
    expected = "sha256=" + hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)


app = Flask(__name__)


@app.post("/o3o/callback")
def o3o_callback():
    raw = request.get_data()                            # thân nguyên văn, trước khi phân tích JSON
    ok = verify_o3o_signature(
        os.environ.get("O3O_EMBED_CALLBACK_SECRET", ""),
        request.headers.get("X-O3O-Timestamp", ""),
        raw,
        request.headers.get("X-O3O-Signature", ""),
    )
    if not ok:
        abort(401)
    event = json.loads(raw)
    print(request.headers.get("X-O3O-Delivery"), event["status"], event["key"], event["version"])
    return "", 204


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=3000)

// Program.cs — ASP.NET Core (.NET 8)
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

var app = WebApplication.CreateBuilder(args).Build();

app.MapPost("/o3o/callback", async (HttpRequest request) =>
{
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);                // thân nguyên văn
    var raw = buffer.ToArray();
    var ok = VerifyO3OSignature(
        Environment.GetEnvironmentVariable("O3O_EMBED_CALLBACK_SECRET") ?? "",
        request.Headers["X-O3O-Timestamp"].ToString(),
        raw,
        request.Headers["X-O3O-Signature"].ToString());
    if (!ok) return Results.Unauthorized();

    using var ev = JsonDocument.Parse(raw);
    Console.WriteLine($"{request.Headers["X-O3O-Delivery"]} {ev.RootElement.GetProperty("status").GetString()} v{ev.RootElement.GetProperty("version").GetInt32()}");
    return Results.NoContent();
});

app.Run("http://0.0.0.0:3000");

static bool VerifyO3OSignature(string secret, string timestamp, byte[] rawBody, string signature, int toleranceSeconds = 300)
{
    if (!long.TryParse(timestamp, out var ts)) return false;
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - ts) > toleranceSeconds) return false;
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var prefix = Encoding.UTF8.GetBytes(timestamp + ".");
    hmac.TransformBlock(prefix, 0, prefix.Length, null, 0);
    hmac.TransformFinalBlock(rawBody, 0, rawBody.Length);
    var expected = "sha256=" + Convert.ToHexString(hmac.Hash!).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(signature));
}

# URL trong callback đã có chữ ký: tải thẳng, không cần khoá
curl -f -o hop-dong-v3.docx "http://localhost:8080/o3o/embed/files/doc_9835f61009fc659dfedab8696f2d2665?v=3&exp=1790086400&sig=<sig>"
# So với trường sha256 của callback trước khi ghi đè bản gốc
sha256sum hop-dong-v3.docx