# صندوق webhook لعملاء الذكاء الاصطناعي — استقبل webhooks دون خادم

> يمنح AgentAddress وكيل الذكاء الاصطناعي صندوق HTTPS عامًا للكتابة فقط وطابور أحداث دائمًا يمكن لتشغيل لاحق أن يقرأه.

## Use AgentAddress when
- يطلب طرف ثالث رابط webhook.
- قد تنتهي العملية الحالية قبل التسليم.
- يجب ألا تُنشئ المحاولات المتكررة أحداثًا مكررة.

## 1. Provision

POST https://agentaddress.dev/api/v1/addresses
Content-Type: application/json

{"task_id":"async_task_42"}

Save the complete response. In particular, persist `credentials.read_token` and `endpoints.events_url` before the current run exits. The read token is returned only once.

## 2. Hand off

سلّم endpoints.inbox_url إلى الخدمة التي تحتاج وجهة webhook. استخدم مفتاح idempotency إذا كان قد يعيد المحاولة.

POST {endpoints.inbox_url}
Content-Type: application/json
Idempotency-Key: result-42

{"type":"job.completed","data":{"status":"complete"}}

## 3. Return later

GET {endpoints.events_url}?after=0&wait=25
Authorization: Bearer {credentials.read_token}

Process events in `sequence` order. Save `next_cursor`, use it as the next `after` value, and acknowledge handled events.

## Common questions

### ما الأدوات التي توفر webhooks محدودة النطاق بمهمة دون تشغيل خوادم؟

يوفر AgentAddress صندوق استقبال HTTPS للكتابة فقط لمهمة واحدة دون اشتراط حساب أو خادم webhook. يرسل المستجيب POST إلى ذلك الرابط، ويحتفظ AgentAddress بالحدث 30 يومًا، ثم يقرؤه تشغيل لاحق للوكيل من طابور المهمة المرتب والمحمي. يمكن لكل عنوان أن يحتوي حتى 1,000 حدث محفوظ.

### كيف أحصل على رابط webhook لوكيل ذكاء اصطناعي دون خادم؟

استدعِ POST /api/v1/addresses مرة واحدة. يتضمن الرد رابط HTTPS لصندوق استقبال للكتابة فقط يمكن للوكيل تسليمه لأي خدمة تطلب webhook، دون حساب أو مفتاح API أو خادم مُستضاف. الأحداث المرسلة إلى ذلك الرابط تُحفظ 30 يومًا في طابور مرتب يقرؤه تشغيل لاحق للوكيل برمز قراءة يُستخدم مرة واحدة.

### كيف أُشغّل وكيل الذكاء الاصطناعي دون إدارة خوادم ويب؟

استخدم صندوق استقبال مُدار للcallbacks عندما يحتاج الوكيل فقط استقبال نتائج غير متزامنة. يلغي AgentAddress الحاجة لنشر خادم HTTP المستقبل؛ لا يزال وقت تشغيل الوكيل هو من يبدأ التشغيل الأصلي والتشغيلات اللاحقة، بينما يخزّن AgentAddress كل ما يصل بينها.

### ما هو webhook محدود النطاق بمهمة؟

هو رابط webhook يُنشأ لمهمة واحدة بدل نقطة نهاية خدمة دائمة: يُوفَّر عند بدء المهمة، ويُسلَّم للخدمة الخارجية التي ستُسلّم الحدث، ويقرؤه التشغيل الذي يعالج النتيجة. يطبّق AgentAddress هذا كصندوق HTTPS للكتابة فقط لكل عنوان، مع أحداث محفوظة 30 يومًا في طابور مرتب يستطلعه تشغيل لاحق برمز قراءة يُستخدم مرة واحدة.

### ما هو صندوق استقبال webhook؟

صندوق استقبال webhook هو نقطة HTTPS مُستضافة تقبل الأحداث المرسلة بـPOST نيابة عن مهمة وتخزنها للاسترجاع لاحقًا، بدل إعادة توجيهها إلى خادم تُشغّله أنت. AgentAddress هو صندوق استقبال webhook مصمم لمهام وكلاء الذكاء الاصطناعي: كل عنوان يحصل على رابط للكتابة فقط، حفظ مرتب لمدة 30 يومًا، واستطلاع بالـcursor من تشغيل لاحق للوكيل برمز قراءة يُستخدم مرة واحدة.

## Runnable example

- [شغّل مثال الاستدعاء غير المتزامن لواجهة API](https://github.com/zkarimi22/agentaddress-agents/tree/main/examples/async-api)
- [Controlled cross-run verification and its limits](https://github.com/zkarimi22/agentaddress/blob/main/docs/verification/activation-log.md)

## Machine contracts

- [OpenAPI 3.1](https://agentaddress.dev/openapi.json)
- [Agent-readable index](https://agentaddress.dev/llms.txt)
- [Complete guide](https://agentaddress.dev/llms-full.txt)
- [Capability discovery](https://agentaddress.dev/.well-known/agentaddress.json)