Siirry sisältöön
Sursa Developers

PATCH/v1/webhooks/{webhook_id}

Päivitä webhook

update_webhook

Muuttaa URL-osoitetta, kuvausta, tilauksia, käyttöoikeuksia, suodattimia, mukautettuja otsakkeita, lähtevää valtuutusta ja käytössäolon tilaa. active: true ottaa webhookin käyttöön ja poistaa keskeytyksen, joten kertyneet toimitukset lähtevät järjestyksessä. active: false poistaa webhookin käytöstä ja peruu odottavat toimitukset. headers korvaa koko mukautettujen otsakkeiden listan; kohde ilman value-kenttää säilyttää samannimisen otsakkeen aiemman arvon. auth: null ja data_profile_id: null poistavat lähtevän valtuutuksen ja dataprofiilin.

Todennus

Lähetä API-avain Authorization-otsakkeessa: Authorization: Bearer <avain>.

Polkuparametrit

  • webhook_idintegerpakollinen

Otsakeparametrit

  • Idempotency-Keystring

    Avain kirjoituksen turvalliseen uusintayritykseen: 1–255 tulostettavaa ASCII-merkkiä; suositus on yksi UUID v4 jokaista loogista toimintoa kohden. Uusintayritys samalla avaimella 24 tunnin kuluessa ei suorita toimintoa uudelleen: se palauttaa tallennetun vastauksen (tila, otsakkeet ja runko) Idempotency-Replayed: true -otsakkeella. Sama avain eri metodilla, polulla, Content-Type-arvolla tai rungolla palauttaa 409 api.idempotency_mismatch; kun ensimmäinen pyyntö on vielä käynnissä, vastaus on 409 api.idempotency_in_progress ja Retry-After: 1. 5xx- tai 429-vastauksen jälkeen avain vapautuu, ja uusintayritys suorittaa toiminnon uudelleen. Avain on sidottu organisaatioon ja kutsujaan (API-avain, käyttäjä tai mukautetun lähteen avain).

    length ≥ 1, length ≤ 255

Pyynnön runko

application/json

Objekti: WebhookUpdate

  • urlstring | null

    length ≤ 2048

  • descriptionstring | null

    length ≤ 200

  • eventsarray of WebhookEventFilter | null

    items ≥ 1

  • activeboolean | null
  • rolestring | null

    Sallitut arvot: admineditorviewernull

  • data_profile_idinteger | null

    null poistaa dataprofiilin.

  • collection_idsarray of integer | null

    Webhookin kokoelmat. Tyhjä luettelo tarkoittaa kaikkia kokoelmia, jotka ovat roolin ja dataprofiilin käytettävissä; puuttuva arvo tai null jättää ne ennalleen. Avain, joka on itse rajattu kokoelmiin, näkee ja muuttaa vain webhookeja, joiden kokoelmat ovat sen luettelossa (muut webhookit palauttavat 404 webhooks.not_found). Tyhjä luettelo tai sen luettelon ulkopuolinen kokoelma palauttaa 403 webhooks.collections_outside_key.

    items ≤ 200

  • tagsarray of string | null

    items ≤ 50

  • payloadstring | null

    Sallitut arvot: fullthinnull

  • headersarray of WebhookHeaderInput | null

    items ≤ 10

  • authWebhookAuthInput | null

    null poistaa lähtevän valtuutuksen.

Vastaukset

200Onnistunut vastaus

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

  • Idempotency-Replayed

    true tarkoittaa, että vastaus toistettiin tälle Idempotency-Key-arvolle tallennetusta vastauksesta: toimintoa ei suoritettu uudelleen.

application/json

Objekti: WebhookEndpoint

  • idintegerpakollinen
  • urlstringpakollinen
  • descriptionstringpakollinen
  • eventsarray of WebhookEventFilterpakollinen
  • activebooleanpakollinen
  • statusWebhookStatuspakollinen
  • paused_atstring (date-time) | null
  • paused_reasonstring | null

    failures: 10 epäonnistunutta yritystä peräkkäin; feature_disabled: paketti ei sisällä webhookeja.

  • disabled_reasonstring | null

    gone: vastaanottaja vastasi koodilla 410; manual: ylläpitäjä poisti webhookin käytöstä.

    Sallitut arvot: gonemanualnull

  • disabled_atstring (date-time) | null
  • roleWebhookRolepakollinen
  • data_profile_idinteger | null

    Webhookin dataprofiili (null tarkoittaa, ettei profiilia ole, kuten API-avaimella, jolla on sama rooli).

  • collection_idsarray of integerpakollinen

    Kokoelmat, joiden tapahtumia webhook vastaanottaa; tyhjä tarkoittaa kaikkia roolin ja dataprofiilin sallimia kokoelmia.

  • tagsarray of stringpakollinen

    Korttitapahtumat vain korteista, joilla on jokin näistä tunnisteista; tyhjä tarkoittaa, ettei suodatinta ole.

  • payloadWebhookPayloadModepakollinen
  • headersarray of WebhookHeaderpakollinen
  • auth_typestring | null

    Lähtevän valtuutuksen tyyppi (null tarkoittaa, ettei sitä ole).

    Sallitut arvot: bearerbasicnull

  • auth_setbooleanpakollinen

    Onko lähtevä valtuutus asetettu (arvoja ei koskaan palauteta).

  • previous_secret_valid_untilstring (date-time) | null

    Mihin asti toimitukset allekirjoitetaan myös edellisellä salaisuudella (null tarkoittaa, ettei päällekkäisyysjaksoa ole).

  • healthWebhookHealth
  • consecutive_failuresintegerpakollinen
  • 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)pakollinen
  • updated_atstring (date-time)pakollinen
400Pyyntö on virheellinen: parametrin arvo tai objektin tila ei salli toimenpidettä (`detail` on viesti).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

401Tunnistetietoja ei lähetetty (ei istuntoevästettä eikä API-avainta), tai avainta ei löytynyt.

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

403Toimenpide ei ole sallittu: rooli ei riitä, kokoelmaan tai korttiin ei ole käyttöoikeutta, pyyntö suoritetaan ”View as” -tilassa, tai organisaation toiminta on keskeytetty tai organisaatio on poistettu (`detail` on objekti, jossa on `code: org_suspended | org_deleted`).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

404Objektia ei ole tai se ei ole saatavillasi. API ei paljasta, onko rajoitettu objekti olemassa.

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

422Validointivirhe: runko tai parametrit eivät vastaa skeemaa (`detail` on validointivirheiden lista), tai parametrin arvo on sallitun alueen ulkopuolella (`detail` on viesti).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

429Liian monta pyyntöä (`api.rate_limited`), organisaation minuutti-, päivä- tai kuukausikiintiö on käytetty (`api.quota_exceeded`; `error.details` sisältää kentät `quota`, `limit` ja `reset_at`), organisaation raja on saavutettu tai vastauspalvelu on kuormitettu (`answers.engine_busy`). Odota `Retry-After`-otsakkeen ilmoittama aika.

Vastausotsakkeet

  • Retry-After

    Kuinka monta sekuntia odotetaan ennen pyynnön uusintayritystä.

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

Virhekoodit

Koodit, jotka tämä päätepiste voi palauttaa error.code-kentässä kaikkien pyyntöjen yleisten koodien lisäksi.

Turvalliset uusintayritykset

Lähetä jokaisen POST- ja PATCH-pyynnön mukana Idempotency-Key-otsake (esimerkiksi UUID). Kun pyyntö toistetaan samalla avaimella 24 tunnin kuluessa, palautetaan tallennettu vastaus eikä pyyntöä suoriteta uudelleen.

Nopeusrajoitukset

Vastauksissa ovat RateLimit- ja RateLimit-Policy-otsakkeet sekä aiemmat X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. 429-vastauksessa on Retry-After sekunteina: odota ja yritä uudelleen.

← webhooks · API-viite