RResumezBeta
API reference/Automation/Webhooks
POSTLive

Create webhook

Registers an HTTPS endpoint that receives the caller's domain events, HMAC-signed.

/v1/webhooks

Authorization

Credential

oauth_user

Required scopes

webhooks:manage

Request body

JSON · application/json

urlstringrequired
eventTypesarray

Implementation note

The response includes `secret` EXACTLY ONCE — verify each delivery by HMAC-SHA256 over "<t>.<body>" against the `X-Resumez-Signature: t=…,v1=…` header. `eventTypes` are type prefixes (empty = all domain events; `api.write` audit events are never delivered). Payloads are thin event records; fetch details over /v1. Retries back off over ~2.5h; 10 consecutive dead deliveries disable the endpoint. Max 10 webhooks (409 beyond that).

Error responses

400Invalid request

The request body was missing, malformed, or failed schema validation. Field-level problems are listed under `issues`.

401Authentication required

No valid credentials were supplied. Attach a Bearer access token and retry.

402Upgrade required

The authenticated user's plan does not include this capability. `feature` names the gated capability, `requiredPlan` the cheapest plan that unlocks it, `currentPlan` the user's plan today, and `upgradeUrl` links to checkout. This is a plan gate, not a transient error — retrying without upgrading fails again; surface `upgradeUrl` to the user instead. Dormant until a plan that grants the feature is active, so a route that documents it may not currently return it.

403Insufficient scope

The token is valid but lacks the OAuth scope (or token kind) this endpoint requires.

409Conflicting state

The resource is in a state that does not allow this operation (e.g. a terminal application stage or an already-decided offer).