API webhooków

API webhooków pozwala programowo subskrybować zdarzenia. Używaj go do natychmiastowych wyzwalaczy w stylu Zapier lub niestandardowych integracji wymagających powiadomień w czasie rzeczywistym.

Uwaga: API webhooków wymaga planu Hobby lub wyższego z aktywnymi rozliczeniami.

Endpointy

Tworzenie subskrypcji

POST /api/v1/webhooks/subscribe

Treść żądania

{
  "event": "form_submission",
  "targetUrl": "https://your-server.com/webhook",
  "chatbotId": "123e4567-e89b-12d3-a456-426614174000"
}

Parametry

Odpowiedź

Sukces (201):

{
  "id": "subscription-uuid"
}

Przykład

curl -X POST 'https://your-domain.com/api/v1/webhooks/subscribe' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "form_submission",
    "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef",
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000"
  }'

Usuwanie subskrypcji

DELETE /api/v1/webhooks/subscribe/[id]

Odpowiedź

Sukces (200): Zwraca pustą odpowiedź ze statusem 200.

Przykład

curl -X DELETE 'https://your-domain.com/api/v1/webhooks/subscribe/sub_abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Lista agentów

Pobierz listę dostępnych agentów, do których można utworzyć subskrypcję:

GET /api/v1/chatbots

Odpowiedź

{
  "chatbots": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Support Bot",
      "url": "https://your-domain.com/chat/support-bot"
    }
  ]
}

Ładunek webhooka

Gdy wystąpi zdarzenie, wysyłamy żądanie POST na Twój docelowy adres URL:

Zdarzenie przesłania formularza

{
  "event": "form_submission",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "data": {
    "id": "lead-uuid",
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+1234567890",
    "conversationId": "conv_abc123",
    "createdAt": "2025-01-10T12:00:00Z"
  },
  "timestamp": "2025-01-10T12:00:00Z"
}

Nagłówki

Z każdą dostawą dołączamy następujące nagłówki:

Content-Type: application/json
User-Agent: AgentkitWebhook/2.0
X-Agentkit-Event: form_submission
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=<unix-seconds>,v1=<hex-hmac-sha256>

Zweryfikuj podpis względem dokładnej, surowej treści żądania w UTF-8, zanim sparsujesz JSON. Zobacz Bezpieczeństwo webhooków, gdzie znajdziesz procedurę podpisywania i katalog ładunków.

Wymagania dotyczące adresu URL

Bezpieczeństwo

Na produkcji adres URL subskrypcji musi używać HTTPS. Poza produkcją akceptowane jest również HTTP — ale dozwolone są wyłącznie adresy URL zaczynające się od http: i https:, a każdy adres URL musi dodatkowo przejść kontrolę publicznego miejsca docelowego dotyczącą samego adresu URL, która odrzuca localhost i podobne nazwy hostów loopback, dosłowne adresy prywatne i link-local oraz endpointy metadanych chmury.

Pełną listę ograniczeń dotyczących miejsca docelowego znajdziesz w Bezpieczeństwie webhooków — to kanoniczny opis tej zasady.

Walidacja

Adres URL jest sprawdzany w momencie tworzenia subskrypcji; adresy URL, które nie przejdą powyższych kontroli, są odrzucane z błędem 400, którego treść wskazuje wymóg dotyczący produkcji. Kontrola sprawdza adres URL dokładnie tak, jak został zapisany — nie rozwiązuje nazw hostów, więc skieruj subskrypcję na publiczny endpoint, na którym rzeczywiście chcesz odbierać zdarzenia. W momencie dostarczenia nazwa hosta jest rozwiązywana jednokrotnie, każdy rozwiązany adres musi być publiczny, a połączenie jest przypięte do tych adresów — nazwa hosta wskazująca na adres prywatny lub wewnętrzny (także taka, która zmienia się między rozwiązaniem a połączeniem) nigdy nie jest kontaktowana; próba jest rejestrowana jako target_blocked.

Niezawodność

Wymagania dotyczące odpowiedzi

Twój endpoint powinien:

• Zwracać status 2xx w ciągu 10 sekund
• Obsługiwać zduplikowane dostawy (być idempotentny)

Obsługa błędów

• Nieudane dostawy są ponawiane pięć razy po żądaniu początkowym
• Jedno wyczerpane zdarzenie zwiększa licznik kolejnych niepowodzeń o jeden
• Co najmniej 10 wyczerpanych zdarzeń w ciągu siedmiu dni automatycznie wyłącza subskrypcję
• Właściciele mogą naprawić i ponownie włączyć subskrypcje w ustawieniach webhooków
• Dostarczenie następuje co najmniej raz — użyj eventId do zapewnienia idempotencji i nie zakładaj zachowania kolejności

Odpowiedzi błędów

Integracja z Zapier

Te endpointy obsługują naszą integrację z Zapier. Gdy łączysz Agentkit z Zapier:

1. Zapier wywołuje /api/v1/auth, aby zweryfikować Twój klucz API
2. Zapier wywołuje /api/v1/chatbots, aby pobrać listę Twoich agentów
3. Gdy włączysz wyzwalacz, Zapier wywołuje /api/v1/webhooks/subscribe
4. Zdarzenia są dostarczane pod adres URL webhooka Zapier
5. Gdy go wyłączysz, Zapier wywołuje DELETE na subskrypcji

Aby zintegrować się bez pisania kodu, skorzystaj bezpośrednio z Zapier zamiast z tych API.

Skonfiguruj Zapier →

Przykład kodu

Menedżer subskrypcji w Node.js

class WebhookManager {
  constructor(apiKey, baseUrl) {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async subscribe(chatbotId, targetUrl, event = 'form_submission') {
    const response = await fetch(`${this.baseUrl}/api/v1/webhooks/subscribe`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ event, targetUrl, chatbotId }),
    });

    if (!response.ok) {
      throw new Error(`Subscribe failed: ${response.status}`);
    }

    return response.json();
  }

  async unsubscribe(subscriptionId) {
    const response = await fetch(
      `${this.baseUrl}/api/v1/webhooks/subscribe/${subscriptionId}`,
      {
        method: 'DELETE',
        headers: { 'Authorization': `Bearer ${this.apiKey}` },
      },
    );

    return response.ok;
  }
}

Kolejne kroki

• Skonfiguruj zbieranie leadów, aby generować zdarzenia
• Skonfiguruj webhooki w interfejsie z poziomu panelu
• Połącz się z Zapier — ponad 5000 integracji