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 بنویسید: یک رویداد ممکن است بیش از یک بار برسد.