مستندات

REST API

وب‌هوک‌ها

با هر تغییر پروفایل، یک درخواست امضاشده دریافت کنید و طرز تأیید آن.

به‌جای پرسیدن مداوم از API، یک وب‌هوک اضافه کنید تا هر وقت چیزی تغییر کرد ما سرور شما را صدا بزنیم. وب‌هوک در پلن حرفه‌ای و بالاتر است (به پلن‌ها نگاه کنید). از پنل، بخش توسعه‌دهندگان ← وب‌هوک‌ها اضافه‌اش کنید.

رویدادها

رویداد چه زمانی
profile.updated یکی از فیلدهای پروفایل تغییر کرد. data.changed فیلدها را نشان می‌دهد.
avatar.changed آواتاری بارگذاری یا حذف شد.
verification.added حساب تأییدشده‌ای اضافه شد (data.network و data.identifier).
verification.removed حساب تأییدشده‌ای حذف شد.
ping آزمایشی که از پنل می‌فرستید.

درخواست

ما یک POST با بدنه‌ی JSON به آدرس شما می‌فرستیم. آدرس باید https و عمومی باشد: نشانی‌های خصوصی، loopback و link-local رد می‌شوند، ریدایرکت دنبال نمی‌شود و نام‌کاربری/رمز داخل آدرس مجاز نیست.

{
  "id": "5b1e0b0e-6a4c-4e5e-9c53-1d3f4b8c8d11",
  "type": "profile.updated",
  "created_at": "2026-11-18T12:00:00+00:00",
  "data": {
    "changed": ["headline"],
    "username": "javid",
    "profile_url": "https://avatarak.ir/javid",
    "email_hashes": ["9d86ec2b…"]
  }
}

email_hashes هش SHA-256 ایمیل‌های تأییدشده‌ی خودتان است تا رویداد را به کاربر سمت خودتان وصل کنید. خود ایمیل هرگز در پیام نیست.

هدرها: Avatarak-Event، Avatarak-Delivery (همان id رویداد؛ برای نادیده گرفتن تکراری‌ها) و Avatarak-Signature.

تأیید امضا

هر وب‌هوک یک رمز (whsec_…) دارد که فقط یک بار هنگام ساخت نشان داده می‌شود. هدر امضا به شکل t=<زمان یونیکس>,v1=<hex> است و v1 برابر HMAC-SHA256(secret, "<t>.<بدنه‌ی خام>") است. امضا را با بدنه‌ی خامِ درخواست بسنجید و زمان‌های قدیمی را رد کنید (۵ دقیقه مناسب است).

use Avatarak\Webhook;

$ok = Webhook::verify(file_get_contents('php://input'), $_SERVER['HTTP_AVATARAK_SIGNATURE'] ?? null, $secret);
import { verifyWebhook } from '@avatarak/client';

const ok = await verifyWebhook(rawBody, req.headers['avatarak-signature'], secret);

تلاش دوباره

ظرف ۸ ثانیه با هر کد 2xx پاسخ دهید. در غیر این صورت تا ۵ بار با فاصله‌های بیشتر (۳۰ ثانیه، ۲ دقیقه، ۱۰ دقیقه، ۱ ساعت) دوباره می‌فرستیم. بعد از ۲۰ شکست پیاپی وب‌هوک خودکار خاموش می‌شود؛ از پنل دوباره روشنش کنید. پردازشگرتان را idempotent بنویسید: یک رویداد ممکن است بیش از یک بار برسد.