Webhooks

Manage webhook subscriptions for the Oho event bus.

📄️Replace webhook

Wholesale replace of subscription properties (signing secret preserved).

📄️List webhook subscriptions

Search subscriptions. Filter by `status` (ACTIVE / DISABLED / AUTO_DISABLED) or `event` (subscriptions interested in a specific event type). Soft-deleted entries are excluded by default.

Create a new subscription. Server generates a synthetic `whk_<16chars>` ID and a fresh signing secret. The plaintext secret is returned ONCE in the response (under `attributes.delivery.signingSecret`); subsequent reads only return `signingSecretLastFour`. Save the returned secret — there is no API to recover it. Use `/rotate` to replace it.

📄️Rotate the signing secret

Generate a fresh HMAC signing secret and return it ONCE. Save the returned value — there is no API to recover it. Rotation keeps the superseded secret alive for a configurable overlap window (default 24h): during the window every delivery is signed with BOTH secrets (two `v1=` entries in `X-Oho-Signature`), so a receiver still verifying with the old secret keeps working until it rolls to the new one. After the window the old secret is no longer honoured.

📄️Redrive failed deliveries

Replay failed deliveries from the audit history. Body filters by `startTimeMillis` / `endTimeMillis` and/or `outcomes` (e.g. `['FAILED_RETRYABLE', 'EXHAUSTED']`). Each unique deliveryId is replayed once with the original stored payload. Truncated payloads (rare; > 64KB) are skipped — the receiver would see incomplete data.

📄️Send a test event to a subscription

Synchronously deliver a synthetic `webhook.test` event to this subscription's URL, bypassing the event-pattern filter and active-status check. Returns the outcome of the single delivery attempt — useful for sanity-checking a freshly-created endpoint or troubleshooting why production events aren't arriving.

📄️Enable a subscription

Sets status to ACTIVE — events resume delivery.

📄️Disable a subscription

Sets status to DISABLED — events stop being delivered until /enable.

📄️List delivery history

Paginated timeseries of delivery attempts for this subscription — one entry per attempt, ordered newest-first. Use this for support diagnostics and to find the deliveryId of a failed attempt to redrive. Default cap: 200 entries; max 1000.

📄️List subscribable event types

Return the catalogue of event types webhooks can subscribe to. Each entry has a `category` (lifecycle / transition / state / utility) for grouping. Subscriptions accept exact event types (e.g. `recruitmentCheck.created`) and wildcards: `<resource>.*` (every event in a resource), `*.<action>` (every event with an action across resources), or `*` (firehose). Wildcards are validated against this catalogue at subscription time — patterns that match nothing are rejected.