Create a webhooksubscription

Required capability: webhook/manage.

Credential scopes: webhooks:write.

The acting subject must also be allowed to perform this action in the organisation.

POST

https://your-organisation.quirelms.com/api/v1/webhook_subscriptions

Authorisation

Quire-Versionoptionalstring
The dated API revision to serve this request at. Omitted, the request is served at the revision the credential was issued against. The response echoes the revision actually applied.

format: date
Idempotency-Keyoptionalstring
A caller-chosen key making this request safe to retry. A replay of a completed request returns the recorded response with Idempotency-Replayed: true. Reusing a key for a different request is refused.

maxLength: 255

urlstringrequired
An https endpoint. It receives a webhook.ping to verify before the subscription is enabled.

format: uri, maxLength: 2000
event_typesarray ofstringrequired
Event names from the public catalog, area.* for an area, or * for everything.

maxLength: 100
descriptionoptionalstringornull
2 variants
One of the following:
string
null
notification_emailsoptionalarray ofstring
format: email, pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
rate_limit_per_minuteoptionalinteger
maximum: 6000, minimum: 1
filtersoptionalmap<unknown>ornull
2 variants
One of the following:
map<unknown>
null

Success.

JSON

idstringrequired
external_idstring | nullrequired
urlstringrequired
event_typesarray ofstringrequired
filtersOption 1ornullrequired
2 variants
One of the following:
Option 1
null
descriptionstring | nullrequired
statusenabledordisabledorauto_disabledrequired
notification_emailsarray ofstringrequired
rate_limit_per_minuteintegerrequired
maximum: 9007199254740991, minimum: -9007199254740991
payload_versionintegerrequired
maximum: 9007199254740991, minimum: -9007199254740991
verified_atstringornullrequired
2 variants
One of the following:
string
null
consecutive_failuresintegerrequired
maximum: 9007199254740991, minimum: -9007199254740991
last_success_atstringornullrequired
2 variants
One of the following:
string
null
disabled_reasonstring | nullrequired
created_atstringrequired
RFC 3339 timestamp in UTC.
updated_atstringrequired
RFC 3339 timestamp in UTC.
secretstringrequired
The signing secret, whsec_ followed by base64. Shown once: store it now.

The credential is missing, malformed, expired or revoked.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

The credential lacks the scope this operation requires, or the acting subject lacks the capability.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

The request conflicts with the current state, with a previous use of the same idempotency key, or with a concurrent write.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

The request was understood and its content is not valid. errors names each field.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

A rate limit or a concurrency cap was reached. Retry-After says when to try again.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null

Something failed at our end. Quote request_id when reporting it.

JSON

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
codestringrequired
categoryvalidationorauthenticationorauthorizationornot_foundorconflictorprecondition+4 morerequired
detailstringrequired
request_idstringrequired
docs_urlstringrequired
format: uri
errorsoptionalarray ofobject
3 properties
- pathstringrequired
  RFC 6901 JSON Pointer into the request body.
- codestringrequired
- detailstringrequired
retry_afteroptionalinteger | null