OZozav
Webhooks

Register a webhook endpoint

Registers an HTTPS endpoint to receive signed event notifications for the subscribed enabled_events. The signing secret (ozav_whsec_) is returned exactly once, in this response - store it securely; it is used to verify delivery signatures and cannot be retrieved again.

The hostname is checked at registration. A host that does not resolve is refused with 422 WEBHOOK_URL_HOST_NOT_FOUND, because a typo there fails silently forever: deliveries never reach anything and the only trace is a null response_status in GET /webhook-endpoints/{id}/deliveries. Only a non-existent hostname is refused - an endpoint behind a firewall, not yet deployed, or slow to answer registers normally.

post/webhook-endpoints

Request

  • Base URL
    https://developers.ozav.io/v2
  • Auth
    • API key in header X-API-Key
    • or HTTP bearer

Request body

urlstring uri required

HTTPS URL that will receive signed POST deliveries.

enabled_eventsWebhookEventType[] required

Event types to deliver to this endpoint.

descriptionstring

Optional human-readable label for the endpoint.

Response

Endpoint registered; the signing secret is in secret (shown once).

idstring required

Opaque webhook endpoint identifier, prefixed ozav_wh_.

object'webhook_endpoint' required

Resource type discriminator; always the literal webhook_endpoint.

urlstring uri required

The HTTPS URL that receives the deliveries. Verify the signature on every request to it (see the Webhooks section); an unverified receiver accepts forged events.

enabled_eventsWebhookEventType[] required

The event types this endpoint is subscribed to. An event whose type is not listed here is never delivered to this endpoint, and no record of a skipped delivery is created.

status'active' | 'disabled' required

active - deliveries are attempted. disabled - nothing is delivered and nothing is queued for later; events that occur while disabled are not replayed on re-enable.

OZAV does not disable an endpoint on its own. A URL that has failed every delivery for weeks still reads active, so status alone is not a health signal - read health.

descriptionstring nullable

Free-form label you set. Never used for routing or delivery.

created_atstring date-time required

When the endpoint was registered (RFC 3339, UTC).

updated_atstring date-time required

When the endpoint was last modified (RFC 3339, UTC).

secretstring

Signing secret (ozav_whsec_...); returned only on creation and rotation.

Changes

No recorded changes to this operation across all 1 revision of this API.