> ## Documentation Index
> Fetch the complete documentation index at: https://www.krea.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# الويب هوك

> قم بإعداد الويب هوك لتلقي أحداث اكتمال المهام في الوقت الفعلي، وقلل الاستعلام، وابنِ مسارات عمل غير متزامنة موثوقة في تطبيقك.

## نظرة عامة

بدلًا من الاستعلام عن `GET /jobs/{id}` بشكل متكرر، يمكنك توفير رابط ويب هوك لتلقّي طلب POST عند اكتمال المهمة. هذا أكثر كفاءة ويُقلل من مكالمات API غير الضرورية.

## استخدام الويب هوك

أضف رأس `X-Webhook-URL` إلى أي طلب توليد. عندما تصل المهمة إلى حالة نهائية (مكتملة أو فاشلة أو ملغاة)، سترسل واجهة API طلب POST إلى رابطك يحتوي على بيانات المهمة الكاملة.

<CodeGroup>
  ```javascript Node.js theme={null}
  // npm install @krea-ai/sdk
  import { Krea } from "@krea-ai/sdk";

  const krea = new Krea({ apiKey: process.env.KREA_API_KEY });

  const job = await krea.image(
    "bfl/flux-1-dev",
    {
      prompt: "a serene mountain landscape at sunset",
      width: 1024,
      height: 576
    },
    { webhookUrl: "https://your-server.com/webhook" }
  );

  console.log(`Job ID: ${job.job_id}`);
  // Your webhook will receive the results when complete
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.krea.ai/generate/image/bfl/flux-1-dev \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -H "X-Webhook-URL: https://your-server.com/webhook" \
    -d '{
      "prompt": "a serene mountain landscape at sunset",
      "width": 1024,
      "height": 576
    }'
  ```

  ```python Python theme={null}
  import requests

  API_BASE = "https://api.krea.ai"
  API_TOKEN = "your-token-secret"

  response = requests.post(
      f"{API_BASE}/generate/image/bfl/flux-1-dev",
      headers={
          "Authorization": f"Bearer {API_TOKEN}",
          "Content-Type": "application/json",
          "X-Webhook-URL": "https://your-server.com/webhook"
      },
      json={
          "prompt": "a serene mountain landscape at sunset",
          "width": 1024,
          "height": 576
      }
  )

  job = response.json()
  print(f"Job ID: {job['job_id']}")
  # Your webhook will receive the results when complete
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      apiBase := "https://api.krea.ai"
      apiToken := "your-token-secret"

      payload := map[string]interface{}{
          "prompt": "a serene mountain landscape at sunset",
          "width":  1024,
          "height": 576,
      }

      jsonData, _ := json.Marshal(payload)
      req, _ := http.NewRequest("POST", apiBase+"/generate/image/bfl/flux-1-dev", bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", "Bearer "+apiToken)
      req.Header.Set("Content-Type", "application/json")
      req.Header.Set("X-Webhook-URL", "https://your-server.com/webhook")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      var job map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&job)
      fmt.Printf("Job ID: %s\n", job["job_id"])
      // Your webhook will receive the results when complete
  }
  ```
</CodeGroup>

## حمولة الويب هوك

عند اكتمال المهمة، يتلقى رابط الويب هوك طلب POST مع بيانات المهمة:

```json theme={null}
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2025-01-15T10:30:00.000Z",
  "completed_at": "2025-01-15T10:30:05.000Z",
  "result": {
    "urls": ["https://..."]
  }
}
```

## أفضل الممارسات

<Check>
  **استجب بسرعة** - أرجع رمز حالة 2xx على الفور. عالج بيانات الويب هوك بشكل غير متزامن عند الحاجة.
</Check>

<Warning>
  **تحقق من الحمولة** - تأكّد من أن `job_id` يطابق مهمة بدأتها قبل معالجة النتائج.
</Warning>

* استخدم نقاط نهاية HTTPS للأمان
* نفّذ آلية عدم التكرار لتفادي التسليمات المكررة
* سجّل استلام الويب هوك لأغراض التصحيح

## الويب هوك مقابل الاستعلام

| الأسلوب       | المزايا                        | العيوب                       |
| ------------- | ------------------------------ | ---------------------------- |
| **الويب هوك** | إشعارات فورية، مكالمات API أقل | يتطلب نقطة نهاية عامة        |
| **الاستعلام** | يعمل في أي مكان، لا حاجة لخادم | مكالمات API أكثر، تأخير طفيف |

استخدم الويب هوك عندما يكون لديك خادم يمكنه استقبال طلبات HTTP. استخدم الاستعلام للتطبيقات على جانب العميل أو عندما لا يمكنك عرض نقطة نهاية عامة.

## الخطوات التالية

<CardGroup cols={2}>
  <Card title="دورة حياة المهمة" icon="cube" href="/developers/job-lifecycle">
    تعرّف على حالات المهمة والاستعلام عن الحالة
  </Card>

  <Card title="أمثلة الكود" icon="code" href="/developers/examples/text-to-image">
    اطّلع على أمثلة كاملة تتضمن معالجة الويب هوك
  </Card>
</CardGroup>