Пређите на садржај
Sursa Developers

POST/v1/webhooks

Креирање вебхука

create_webhook

URL мора да користи https, а његов хост мора да се разрешава у јавне адресе. Приватне мреже (RFC 1918), loopback, link-local, мреже за метаподатке облака и друге мреже посебне намене одбијају се и при регистрацији и при свакој вези. Тајна за потписивање приказује се једном у одговору (secret); после тога може само да се ротира. Организација може да има највише 20 вебхукова.

Претплата наводи типове догађаја и маске група догађаја (card.*, *). Приступ се подешава на исти начин као за API кључ: role, data_profile_id и collection_ids. Догађај о објекту који улога, профил приступа или колекције не могу да виде не испоручује се. tags ограничава догађаје картица на картице које имају било коју од ознака. payload: thin шаље догађаје без data. Прилагођена заглавља (headers) и ауторизација одлазних захтева (auth) чувају се шифровано; одговори садрже само називе заглавља и ознаке value_set и auth_set.

Аутентификација

Пошаљите API кључ у заглављу Authorization: Authorization: Bearer <кључ>.

Параметри заглавља

  • Idempotency-Keystring

    Кључ за безбедан поновни покушај уписа: од 1 до 255 штампаних ASCII знакова; препоручује се UUID v4 за сваку логичку операцију. Поновни покушај са истим кључем у року од 24 сата не извршава операцију поново: враћа сачувани одговор (статус, заглавља и тело) са заглављем Idempotency-Replayed: true. Исти кључ са другим методом, путањом, Content-Type или телом враћа 409 api.idempotency_mismatch; док се први захтев још извршава – 409 api.idempotency_in_progress са Retry-After: 1. После одговора 5xx или 429 кључ се ослобађа и поновни покушај поново извршава операцију. Кључ важи у оквиру организације и позиваоца (API кључ, корисник или кључ сопственог извора).

    length ≥ 1, length ≤ 255

Тело захтева

application/json

Објекат: WebhookCreate

  • urlstringобавезно

    URL примаоца, само https://, до 2048 знакова.

    length ≤ 2048

  • descriptionstring

    length ≤ 200

  • eventsarray of WebhookEventFilterобавезно

    items ≥ 1

  • roleWebhookRole
  • data_profile_idinteger | null
  • collection_idsarray of integer

    Колекције о којима вебхук прима догађаје. Изостанак вредности или празна листа значи све колекције доступне улози и профилу приступа. Кључ који је и сам ограничен на колекције креира вебхук само са непразном листом сопствених колекција. Без овог поља, са празном листом или са колекцијом ван његове листе захтев враћа 403 webhooks.collections_outside_key.

    items ≤ 200

  • tagsarray of string

    items ≤ 50

  • payloadWebhookPayloadMode
  • headersarray of WebhookHeaderInput

    items ≤ 10

  • authWebhookAuthInput

Одговори

201Креирано. Ово је једини пут када се `secret` приказује.

Заглавља одговора

  • RateLimit-Policy

    Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.

  • RateLimit

    Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).

  • X-RateLimit-Remaining

    Број преосталих захтева по најстрожем ограничењу.

  • X-RateLimit-Reset

    Број секунди до ресетовања најстрожег ограничења.

  • Idempotency-Replayed

    true значи да је одговор поново послат из одговора сачуваног за овај Idempotency-Key: операција није поново извршена.

application/json

Објекат: WebhookCreated

  • idintegerобавезно
  • urlstringобавезно
  • descriptionstringобавезно
  • eventsarray of WebhookEventFilterобавезно
  • activebooleanобавезно
  • statusWebhookStatusобавезно
  • paused_atstring (date-time) | null
  • paused_reasonstring | null

    failures: 10 неуспелих покушаја заредом; feature_disabled: план не обухвата вебхукове.

  • disabled_reasonstring | null

    gone: прималац је одговорио са 410; manual: искључио га је администратор.

    Дозвољене вредности: gonemanualnull

  • disabled_atstring (date-time) | null
  • roleWebhookRoleобавезно
  • data_profile_idinteger | null

    Профил приступа вебхука (null значи без профила, као за API кључ са истом улогом).

  • collection_idsarray of integerобавезно

    Колекције о којима вебхук прима догађаје; празно значи све колекције доступне улози и профилу приступа.

  • tagsarray of stringобавезно

    Догађаји картица само за картице са било којом од ових ознака; празно значи без филтера.

  • payloadWebhookPayloadModeобавезно
  • headersarray of WebhookHeaderобавезно
  • auth_typestring | null

    Тип ауторизације одлазних захтева (null значи без ауторизације).

    Дозвољене вредности: bearerbasicnull

  • auth_setbooleanобавезно

    Да ли је ауторизација одлазних захтева подешена (вредности се никада не враћају).

  • previous_secret_valid_untilstring (date-time) | null

    До када се испоруке потписују и претходном тајном (null значи да нема преклапања).

  • healthWebhookHealth
  • consecutive_failuresintegerобавезно
  • last_delivery_atstring (date-time) | null
  • last_success_atstring (date-time) | null
  • last_errorstring | null
  • created_byinteger | null
  • created_by_namestring | null
  • created_atstring (date-time)обавезно
  • updated_atstring (date-time)обавезно
  • secretstringобавезно

    whsec_ и 32 бајта у кодирању base64 (нове тајне користе стандардну абецеду са допуном, старије – base64url). Чувајте је на страни примаоца; више се никада не појављује у одговорима API интерфејса. Кључ за потписивање по спецификацији Standard Webhooks је резултат base64 декодирања дела после whsec_.

  • previous_valid_untilstring (date-time) | null

    До када се претходна тајна још прихвата (после ротације). null при креирању.

400Захтев није исправан: вредност параметра или стање објекта не дозвољава радњу (`detail` је порука).

Заглавља одговора

  • RateLimit-Policy

    Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.

  • RateLimit

    Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).

  • X-RateLimit-Remaining

    Број преосталих захтева по најстрожем ограничењу.

  • X-RateLimit-Reset

    Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

401Акредитиви нису послати (ни колачић сесије ни API кључ) или кључ није пронађен.

Заглавља одговора

  • RateLimit-Policy

    Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.

  • RateLimit

    Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).

  • X-RateLimit-Remaining

    Број преосталих захтева по најстрожем ограничењу.

  • X-RateLimit-Reset

    Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

403Радња није дозвољена: улога није довољна, нема приступа колекцији или картици, захтев се извршава у режиму „View as“ или је организација суспендована или обрисана (`detail` је објекат са `code: org_suspended | org_deleted`).

Заглавља одговора

  • RateLimit-Policy

    Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.

  • RateLimit

    Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).

  • X-RateLimit-Remaining

    Број преосталих захтева по најстрожем ограничењу.

  • X-RateLimit-Reset

    Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

409Стање објекта не дозвољава радњу, на пример дупликат, индексирање у току или посао који је већ обрађен.

Заглавља одговора

  • RateLimit-Policy

    Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.

  • RateLimit

    Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).

  • X-RateLimit-Remaining

    Број преосталих захтева по најстрожем ограничењу.

  • X-RateLimit-Reset

    Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

422Грешка валидације: тело или параметри не одговарају шеми (`detail` је листа грешака валидације) или је вредност параметра ван дозвољеног распона (`detail` је порука).

Заглавља одговора

  • RateLimit-Policy

    Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.

  • RateLimit

    Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).

  • X-RateLimit-Remaining

    Број преосталих захтева по најстрожем ограничењу.

  • X-RateLimit-Reset

    Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

429Превише захтева (`api.rate_limited`), квота организације за минут, дан или месец је потрошена (`api.quota_exceeded`; `error.details` садржи `quota`, `limit` и `reset_at`), достигнуто је ограничење организације или је сервис за одговоре заузет (`answers.engine_busy`). Сачекајте време наведено у заглављу `Retry-After`.

Заглавља одговора

  • Retry-After

    Број секунди које треба сачекати пре поновног покушаја захтева.

  • RateLimit-Policy

    Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.

  • RateLimit

    Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).

  • X-RateLimit-Remaining

    Број преосталих захтева по најстрожем ограничењу.

  • X-RateLimit-Reset

    Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

Кодови грешака

Кодови које ова операција може да врати у error.code, поред општих кодова сваког захтева.

Безбедни поновни покушаји

Уз сваки POST и PATCH захтев пошаљите заглавље Idempotency-Key (на пример UUID). Поновни покушај са истим кључем у року од 24 сата враћа сачувани одговор уместо да поново изврши захтев.

Ограничења учесталости

Одговори садрже заглавља RateLimit и RateLimit-Policy, као и старија X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. Одговор 429 садржи заглавље Retry-After у секундама: сачекајте и поновите захтев.

← webhooks · API референца