What does the webhook JSON payload look like?

Every webhook payload follows a consistent envelope structure: an event field (the event type like 'post.published'), a timestamp (ISO 8601 UTC), an id (a unique delivery ID for idempotency), and a data object containing the event-specific fields. For a post.published event the data object contains slug, title, url, excerpt, author.name, published_at, and tags (an array of tag names). For subscriber.created it contains email, plan, and created_at. The full JSON schema for each event type is d...

How do I verify that a webhook came from VeloCMS?

Every webhook request includes an X-VeloCMS-Signature header containing an HMAC-SHA256 hex digest of the raw request body, computed using your webhook endpoint's secret key. To verify: in your receiving server, compute HMAC-SHA256 of the raw request body using your secret key, and compare the result to the value in the header. If they match, the request is genuine. If they don't match, reject it with a 401 status. The secret key is shown once when you create the webhook endpoint — store it se...

What HTTP status should my server return?

Return any 2xx status (200, 201, 204) within 10 seconds to acknowledge receipt. VeloCMS considers the delivery successful as soon as it receives any 2xx response — it doesn't parse your response body. If your processing takes longer than 10 seconds, the correct approach is to acknowledge receipt immediately with a 200 OK, then process the payload asynchronously in the background. Returning a 5xx error or letting the connection time out triggers VeloCMS's retry logic (up to 4 attempts with exp...

Can I test webhook deliveries without publishing a real post?

Yes. In Admin → Settings → Integrations → Webhooks, each registered endpoint has a Send Test Event button. Clicking it sends a sample payload of the selected event type to your endpoint URL immediately, using the same signature header as a real event. This lets you verify your receiving server's signature check and response handling without needing to create real content. The test event payload is clearly marked with a 'test': true flag in the JSON so your server can skip processing if it's n...

كيف تعمل الـ Webhooks في VeloCMS؟

الـ webhook في VeloCMS هو طلب HTTP POST صادر يُرسَل إلى رابط تُسجّله أنت كلما وقع حدث محدد في مدونتك — كنشر منشور جديد، أو انضمام مشترك جديد، أو اكتمال طلب شراء. جسم الطلب كائن JSON، ويتضمن الطلب رأس توقيع HMAC-SHA256 حتى يتمكن الخادم المستقبِل من التحقق من أن الطلب صادر فعلًا من VeloCMS.

كيف تبدو بيانات JSON الخاصة بـ webhook؟

تتبع كل بيانات webhook هيكل غلاف موحدًا: حقل event (نوع الحدث مثل 'post.published')، وtimestamp (بتوقيت ISO 8601 UTC)، وid (معرّف تسليم فريد لضمان الأثر الواحد)، وكائن data يحتوي على الحقول الخاصة بكل حدث. لحدث post.published، يتضمن كائن data: الـ slug والعنوان والرابط والمقتطف واسم المؤلف author.name وتاريخ النشر published_at والوسوم tags (مصفوفة بأسماء الوسوم). لحدث subscriber.created، يتضمن: البريد الإلكتروني والخطة وتاريخ الإنشاء created_at. مخطط JSON الكامل لكل نوع حدث موثَّق في مرجع VeloCMS API.

كيف أتحقق من أن webhook صادر من VeloCMS؟

يتضمن كل طلب webhook رأس X-VeloCMS-Signature يحتوي على ملخص hex من نوع HMAC-SHA256 لجسم الطلب الخام، مُحسَبًا باستخدام المفتاح السري لنقطة النهاية الخاصة بك. للتحقق: في الخادم المستقبِل، احسب HMAC-SHA256 لجسم الطلب الخام باستخدام مفتاحك السري، وقارن النتيجة بالقيمة الموجودة في الرأس. إذا تطابقا، فالطلب أصيل. وإذا لم يتطابقا، ارفضه بحالة 401. يُعرَض المفتاح السري مرة واحدة فقط عند إنشاء نقطة النهاية — احفظه بأمان، لأن VeloCMS لن يعرضه مجددًا (وإن كنت تستطيع تدويره من لوحة التكاملات في أي وقت).

ما حالة HTTP التي ينبغي أن يُعيدها الخادم؟

أعِد أي حالة 2xx (200 أو 201 أو 204) في غضون 10 ثوانٍ لتأكيد الاستلام. يعتبر VeloCMS التسليم ناجحًا فور استلامه أي استجابة 2xx — فهو لا يُحلّل جسم استجابتك. إذا استغرقت معالجتك أكثر من 10 ثوانٍ، فالنهج الصحيح هو تأكيد الاستلام فورًا بـ 200 OK ثم معالجة البيانات بصورة غير متزامنة في الخلفية. إعادة خطأ 5xx أو السماح بانتهاء مهلة الاتصال يُشغّل منطق إعادة المحاولة في VeloCMS (ما يصل إلى 4 محاولات مع تراجع أسي). أما إعادة خطأ 4xx (كـ 400 Bad Request) فيُصنّف التسليم فاشلًا نهائيًا دون إعادة محاولة.

هل يمكنني اختبار عمليات تسليم webhook دون نشر منشور حقيقي؟

نعم. في Admin → Settings → Integrations → Webhooks، لكل نقطة نهاية مسجَّلة زر Send Test Event. بالنقر عليه، يُرسَل فورًا بيانات نموذجية لنوع الحدث المحدد إلى رابط نقطة النهاية، مع نفس رأس التوقيع المستخدم في حدث حقيقي. يتيح لك ذلك التحقق من فحص التوقيع في خادمك ومن معالجة الاستجابة دون الحاجة إلى إنشاء محتوى فعلي. بيانات الحدث التجريبي مُميَّزة بوضوح بعلامة 'test': true في JSON حتى يتمكن خادمك من تخطي المعالجة إذا لم يكن مستعدًا بعد للأحداث التجريبية.

معرّف التسليم في غلاف webhook (حقل 'id') ثابت عبر عمليات إعادة المحاولة — فالحدث ذاته يحمل دائمًا نفس معرّف التسليم. استخدم هذا لضمان الأثر الواحد في الخادم المستقبِل: احفظ معرّفات التسليم المُستلَمة وتجاهل المعالجة إذا كنت قد تعاملت مع هذا المعرّف من قبل. هذا يمنع التأثيرات الجانبية المكررة إذا أعاد VeloCMS تسليم حدث قد عالجه خادمك بالفعل.