API başvurusu

Webhook

Bu gruptaki 8 uç.

Webhook'ları listele

GET/api/v1/webhooks

Kapsam
read
SDK metodu
listWebhooks · list_webhooks
MCP aracı
listWebhookssalt okunur

Örnek istek

curl -X GET "https://hiboty.com/api/v1/webhooks" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "url": "https://example.com/hook",
      "description": "string",
      "events": [
        "message.received"
      ],
      "active": true,
      "failure_count": 1,
      "last_status": 1,
      "last_delivery_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ]
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Webhook oluştur

POST/api/v1/webhooks

İmza sırrı (secret) yalnız bu yanıtta döner. Adres herkese açık https olmalıdır; localhost ve özel ağ adresleri 400 döner. Ardışık 50 başarısız teslimde webhook kapanır (active: false); enableWebhook ya da panel ile yeniden açılır. Kapsam: write.

Kapsam
write
SDK metodu
createWebhook · create_webhook
MCP aracı
createWebhookdış etkili

Gövde alanları

AdTürZorunluAçıklama
urlurievetHerkese açık https adresi
descriptionstringhayırlen ≤ 120
eventsenum[]evetOlay adları, ör. message.receiveditems 1–30

Örnek istek

curl -X POST "https://hiboty.com/api/v1/webhooks" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://ornek.com/hiboty-webhook","description":"CRM","events":["message.received","conversation.handoff"]}'

Örnek yanıt (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://example.com/hook",
    "description": "string",
    "events": [
      "message.received"
    ],
    "active": true,
    "failure_count": 1,
    "last_status": 1,
    "last_delivery_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "secret": "string"
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Webhook ayrıntısı

GET/api/v1/webhooks/{id}

İmza sırrı dönmez. Yönetici yetkisi gerekir. Kapsam: webhooks:read.

Kapsam
webhooks:read
SDK metodu
getWebhook · get_webhook
MCP aracı
getWebhooksalt okunur

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

curl -X GET "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://example.com/hook",
    "description": "string",
    "events": [
      "message.received"
    ],
    "active": true,
    "failure_count": 1,
    "last_status": 1,
    "last_delivery_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z"
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Webhook'u günceller

PATCH/api/v1/webhooks/{id}

Yalnız gönderilen alanlar değişir; imza sırrı değişmez. Adres herkese açık https olmalıdır. active true hata sayacını sıfırlar. Yönetici yetkisi gerekir. Kapsam: webhooks:write.

Kapsam
webhooks:write
SDK metodu
updateWebhook · update_webhook
MCP aracı
updateWebhookdış etkili

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Gövde alanları

AdTürZorunluAçıklama
urlurihayırlen ≤ 500
descriptionstringhayırlen ≤ 120
eventsenum[]hayıritems 1–30
activebooleanhayır

Örnek istek

curl -X PATCH "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":["message.received","conversation.handoff"],"active":true}'

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://example.com/hook",
    "description": "string",
    "events": [
      "message.received"
    ],
    "active": true,
    "failure_count": 1,
    "last_status": 1,
    "last_delivery_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z"
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Webhook'u sil

DELETE/api/v1/webhooks/{id}

Kapsam
write
SDK metodu
deleteWebhook · delete_webhook
MCP aracı
deleteWebhookgeri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetWebhook kimliği

Örnek istek

curl -X DELETE "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Kapanmış webhook'u yeniden aç

POST/api/v1/webhooks/{id}/enable

Ardışık 50 başarısız teslimde kapanan webhook'u açar ve hata sayacını sıfırlar. Kapsam: write.

Kapsam
write
SDK metodu
enableWebhook · enable_webhook
MCP aracı
enableWebhookdış etkili

Parametreler

AdTürZorunluAçıklama
idyoluuidevetWebhook kimliği

Örnek istek

curl -X POST "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/enable" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://example.com/hook",
    "description": "string",
    "events": [
      "message.received"
    ],
    "active": true,
    "failure_count": 1,
    "last_status": 1,
    "last_delivery_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z"
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Teslim geçmişini listeler

GET/api/v1/webhooks/{id}/deliveries

Olayın içeriği (kişisel veri taşıyabilir) dönmez; yalnız durum, deneme sayısı ve hata döner. Yönetici yetkisi gerekir. Kapsam: webhooks:read.

Kapsam
webhooks:read
SDK metodu
listWebhookDeliveries · list_webhook_deliveries
MCP aracı
listWebhookDeliveriessalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği
limitsorguintegerhayırSayfa boyutu (1–200, varsayılan 50); tam sayı değilse 400val 1–200, default 50
cursorsorgustringhayırÖnceki yanıttaki next_cursor (opak)

Örnek istek

curl -X GET "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/deliveries?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "event": "message.received",
      "status": "pending",
      "attempts": 1,
      "response_status": 1,
      "error": "string",
      "delivered_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Test olayı (ping) gönderir

POST/api/v1/webhooks/{id}/test

Adrese gerçek bir istek gider (özel ağ adresleri reddedilir). Kapalı webhook 409 webhook_inactive döner. Yönetici yetkisi gerekir. Kapsam: webhooks:write.

Kapsam
webhooks:write
SDK metodu
testWebhook · test_webhook
MCP aracı
testWebhookdış etkili

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

curl -X POST "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/test" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "delivered": true,
    "status": 1
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.webhook_inactive
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.