مستندات وب‌هوک برای توسعه‌دهندگان

{
  "event": "job.completed",
  "job": {
    "id": 9001,
    "title": "راهنمای شروع بازاریابی محتوایی",
    "status": "completed"
  },
  "batch": {
    "id": 501,
    "category": "بازاریابی و تبلیغات"
  },
  "article": {
    "title": "راهنمای شروع بازاریابی محتوایی",
    "summary": "خلاصه‌ی مقاله...",
    "content": "<h1>...</h1><p>محتوای کامل HTML مقاله...</p>",
    "tags": ["بازاریابی محتوایی", "تولید محتوا", "استراتژی دیجیتال"],
    "sections": [
      { "heading": "بازاریابی محتوایی چیست؟", "content": "..." },
      { "heading": "گام‌های اجرای یک استراتژی موفق", "content": "..." }
    ]
  },
  "sent_at": "2026-07-17T10:15:00+03:30"
}

hex( HMAC_SHA256( secret, raw_request_body ) )

const express = require('express');
const crypto = require('crypto');

const app = express();
const WEBHOOK_SECRET = process.env.TEXTOMA_WEBHOOK_SECRET;

// باید بدنه‌ی خام (raw) رو نگه داریم، نه فقط JSON پارس‌شده
app.use(express.raw({ type: '*/*' }));

app.post('/webhooks/textoma', (req, res) => {
  const signature = req.header('X-Textoma-Signature') || '';
  const rawBody = req.body; // Buffer

  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

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

  if (!isValid) {
    return res.status(401).json({ error: 'invalid signature' });
  }

  const payload = JSON.parse(rawBody.toString('utf8'));

  // فوراً ۲۰۰ برگردونید، پردازش سنگین رو async انجام بدید
  res.status(200).json({ received: true });

  switch (payload.event) {
    case 'job.completed':
      console.log('article ready:', payload.article.title);
      break;
    case 'job.failed':
      console.error('job failed:', payload.job.error);
      break;
    case 'job.started':
      console.log('job started:', payload.job.id);
      break;
  }
});

app.listen(3000);

<?php

$secret = getenv('TEXTOMA_WEBHOOK_SECRET');

$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_TEXTOMA_SIGNATURE'] ?? '';

$expected = hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    echo json_encode(['error' => 'invalid signature']);
    exit;
}

$payload = json_decode($rawBody, true);

http_response_code(200);
echo json_encode(['received' => true]);
if (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();
}

switch ($payload['event']) {
    case 'job.completed':
        error_log('article ready: ' . $payload['article']['title']);
        break;
    case 'job.failed':
        error_log('job failed: ' . ($payload['job']['error'] ?? ''));
        break;
    case 'job.started':
        error_log('job started: ' . $payload['job']['id']);
        break;
}

import hashlib
import hmac
import json
import os

from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["TEXTOMA_WEBHOOK_SECRET"]


@app.post("/webhooks/textoma")
def textoma_webhook():
    raw_body = request.get_data()  # بدنه‌ی خام، قبل از هر پارسی
    signature = request.headers.get("X-Textoma-Signature", "")

    expected = hmac.new(
        WEBHOOK_SECRET.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return jsonify({"error": "invalid signature"}), 401

    payload = json.loads(raw_body)

    event = payload.get("event")
    if event == "job.completed":
        print("article ready:", payload["article"]["title"])
    elif event == "job.failed":
        print("job failed:", payload["job"].get("error"))
    elif event == "job.started":
        print("job started:", payload["job"]["id"])

    return jsonify({"received": True}), 200


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

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
)

var webhookSecret = os.Getenv("TEXTOMA_WEBHOOK_SECRET")

type webhookPayload struct {
	Event string `json:"event"`
	Job   struct {
		ID     int    `json:"id"`
		Title  string `json:"title"`
		Status string `json:"status"`
		Error  string `json:"error"`
	} `json:"job"`
	Article struct {
		Title   string `json:"title"`
		Content string `json:"content"`
	} `json:"article"`
}

func sign(secret string, body []byte) string {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(body)
	return hex.EncodeToString(mac.Sum(nil))
}

func handler(w http.ResponseWriter, r *http.Request) {
	rawBody, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "bad request", http.StatusBadRequest)
		return
	}

	signature := r.Header.Get("X-Textoma-Signature")
	expected := sign(webhookSecret, rawBody)

	if !hmac.Equal([]byte(expected), []byte(signature)) {
		http.Error(w, "invalid signature", http.StatusUnauthorized)
		return
	}

	var payload webhookPayload
	if err := json.Unmarshal(rawBody, &payload); err != nil {
		http.Error(w, "invalid json", http.StatusBadRequest)
		return
	}

	w.WriteHeader(http.StatusOK)
	_, _ = w.Write([]byte(`{"received": true}`))

	switch payload.Event {
	case "job.completed":
		log.Println("article ready:", payload.Article.Title)
	case "job.failed":
		log.Println("job failed:", payload.Job.Error)
	case "job.started":
		log.Println("job started:", payload.Job.ID)
	}
}

func main() {
	http.HandleFunc("/webhooks/textoma", handler)
	log.Fatal(http.ListenAndServe(":3000", nil))
}