Skip to content
Qrona Newsletter
Sign inCreate an account

Reference / Webhooks

Create webhook

POST/api/v1/webhooks

A new webhook. The response contains the secret that deliveries are signed with – it is shown only now.

The URL must be https, on the standard port and reachable from the internet. Each delivery is a POST with JSON and the header Qrona-Signature; respond with 2xx within ten seconds. Read more in the webhooks guide.

Guide: webhooks →

Scope

  • webhooks:write Edit webhooks – the person behind the key must be administrator.

Body

JSON, Content-Type: application/json. Unknown fields return 422.

urlstringrequired
The URL that receives the events (https, standard port, reachable from the internet).at most 2048 characters
eventsarray<string>required
The events the webhook should receive: contact.subscribed (sign-up), contact.unsubscribed (unsubscription), contact.bounced (bounce), contact.complained (spam complaint).at least 1 · at most 4
descriptionstring | null
What the webhook is for.at most 200 characters
include_apiboolean
Also send changes made via the API. Default: false, so that an integration is not told about its own changes.

Retrying a request

Feel free to send the Idempotency-Key header (e.g. a UUID). If the same request is sent again with the same key within 24 hours, the first response is returned, without anything being done twice. Batch and idempotency

Response

201 The new webhook, with the secret.

idstringrequired
urlstringrequired
descriptionstring | nullrequired
eventsarray<string>required
include_apibooleanrequired
activebooleanrequired
disabled_reasonstring | nullrequired
Why the webhook disabled itself (the deliveries failed), or null.
consecutive_failuresintegerrequired
Failed delivery attempts in a row.
last_success_atstring (time, ISO 8601) | nullrequired
The last successful delivery.
last_failure_atstring (time, ISO 8601) | nullrequired
The most recent failed attempt.
created_atstring (time, ISO 8601)required
When the webhook was created.
updated_atstring (time, ISO 8601)required
When the webhook was last changed.
secretstringrequired
The secret that the deliveries are signed with (Qrona-Signature). Only shown now – store it with the receiver.

Errors

400
bad_request
401
unauthenticatedinvalid_keykey_revokedkey_expiredkey_inactive
402
payment_required
403
insufficient_scopeforbiddenworkspace_suspended
409
limit_reachedidempotency_in_progress
415
unsupported_media_type
422
validation_failedidempotency_key_reused
429
rate_limited
500
internal_error