Salt la conținut
Sursa Developers

POST/v1/webhooks/{webhook_id}/test

Trimite un eveniment de test

test_webhook

Trimite imediat un eveniment, indiferent de abonări și de starea webhookului, cu test: true, în afara ordinii livrărilor webhookului și fără X-KB-Sequence. Evenimentul nu este înregistrat în fluxul de evenimente. type este orice tip din catalog (implicit webhook.ping); data provine din exemplul evenimentului din secțiunea webhooks a specificației. Un eșec nu este reîncercat și nu contează pentru pragul de pauză. Răspunsul este livrarea, cu codul de răspuns al receptorului și eroarea.

Autentificare

Trimiteți o cheie API în antetul Authorization: Authorization: Bearer <cheie>.

Parametri de cale

  • webhook_idintegerobligatoriu

Parametri de antet

  • Idempotency-Keystring

    Cheie pentru reîncercarea sigură a unei scrieri: 1–255 de caractere ASCII imprimabile; se recomandă un UUID v4 pentru fiecare operație logică. O reîncercare cu aceeași cheie în decurs de 24 de ore nu execută din nou operația: returnează răspunsul salvat (status, antete și corp) cu antetul Idempotency-Replayed: true. Aceeași cheie cu altă metodă, altă cale, alt Content-Type sau alt corp returnează 409 api.idempotency_mismatch; cât timp prima cerere încă rulează – 409 api.idempotency_in_progress cu Retry-After: 1. După un răspuns 5xx sau 429, cheia este eliberată, iar o reîncercare execută din nou operația. Cheia este valabilă în cadrul organizației și al apelantului (cheie API, utilizator sau cheie de sursă personalizată).

    length ≥ 1, length ≤ 255

Corpul cererii

application/json

Obiect: WebhookTestRequest

Răspunsuri

200Livrarea a fost încercată (dacă a reușit se vede în `status`).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

  • Idempotency-Replayed

    true înseamnă că răspunsul a fost redat din cel salvat pentru această cheie Idempotency-Key: operația nu a rulat din nou.

application/json

Obiect: WebhookDelivery

  • expandedWebhookDeliveryExpanded
  • idintegerobligatoriu
  • webhook_idintegerobligatoriu
  • event_idstringobligatoriu

    ID-ul evenimentului (evt_…), trimis și în antetul X-KB-Event-Id și în corpul livrării.

  • event_typeWebhookEventTypeobligatoriu
  • event_created_atstring (date-time)obligatoriu
  • attemptintegerobligatoriu

    Numărul de încercări efectuate.

  • statusWebhookDeliveryStatusobligatoriu
  • response_codeinteger | null
  • duration_msinteger | null
  • next_retry_atstring (date-time) | null
  • errorstring | null
  • delivered_atstring (date-time) | null
  • created_atstring (date-time)obligatoriu
  • updated_atstring (date-time)obligatoriu
  • sequenceinteger | null

    Numărul în ordinea livrărilor webhookului (X-KB-Sequence); null pentru o livrare de test.

  • testbooleanobligatoriu

    O livrare de test (POST /v1/webhooks/{webhook_id}/test).

  • redelivery_ofinteger | null

    Livrarea originală, dacă aceasta este o livrare nouă.

  • error_codestring | null

    Codul neutru al ultimului eșec: timeout, connection_failed, tls_error, private_address, unresolvable, redirect, http_error, request_failed, endpoint_disabled, event_expired; o livrare anulată (cancelled) poate avea și event_not_permitted (evenimentul este în afara drepturilor webhookului în momentul încercării, pentru că drepturile au fost restrânse după distribuirea evenimentului către webhookuri) sau event_unavailable (corpul unei livrări de test nu mai este disponibil).

401Nu au fost trimise date de autentificare (nici cookie de sesiune, nici cheie API) sau cheia nu a fost găsită.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

403Acțiunea nu este permisă: rolul este insuficient, nu există acces la colecție sau la fișă, cererea rulează în modul „View as” (vizualizare ca alt utilizator) sau organizația este suspendată ori ștearsă (`detail` este un obiect cu `code: org_suspended | org_deleted`).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

404Obiectul nu există sau nu vă este disponibil. API-ul nu confirmă existența unui obiect restricționat.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

429Prea multe cereri (`api.rate_limited`), cota organizației pentru minut, zi sau lună este epuizată (`api.quota_exceeded`; `error.details` conține `quota`, `limit` și `reset_at`), limita organizației este atinsă sau serviciul de răspunsuri este ocupat (`answers.engine_busy`). Așteptați timpul indicat în antetul `Retry-After`.

Antetele răspunsului

  • Retry-After

    Numărul de secunde de așteptat înainte de a reîncerca cererea.

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

Coduri de eroare

Codurile pe care acest endpoint le poate returna în error.code, pe lângă codurile generale ale oricărei cereri.

Reîncercări sigure

Trimiteți un antet Idempotency-Key (de exemplu, un UUID) cu fiecare POST și PATCH. O reîncercare cu aceeași cheie în decurs de 24 de ore returnează răspunsul salvat, fără să execute din nou cererea.

Limite de frecvență

Răspunsurile conțin antetele RateLimit și RateLimit-Policy, precum și antetele anterioare X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset. Un răspuns 429 conține Retry-After în secunde: așteptați și reîncercați.

← webhooks · Referința API