Platitun · API · Event subscription · Set the address and events

Set the address and events

PUT /api/v1/hooks

Key scope: hooks · changes data, the Idempotency-Key header is required

The first call creates the subscription and returns the signing secret ONCE. Later calls edit the address and the event set but do NOT change the secret: your signature check is already configured, and changing the secret for you would break it silently.

The address is checked BEFORE EVERY send, not only when saved: a name that looks harmless today may point into an internal network by the time we send. Internal and service addresses are refused outright.

Editing the address CLEARS the pause and resets the failure counter: you fixed exactly what stopped the delivery.

Request fields

Field	Type	What it is
`url` required	`string`	Where to call. https only and a public host only.
`events` required	`array`	What to call about. An empty set is refused: a subscription to nothing would look alive and stay silent.

Response fields

Field	Type	What it is
`secret`	`string\|null`	The signing secret — only when the subscription is created. Empty on an edit.
`events`	`array`	The set as the server understood it: junk and duplicates removed.

Refusal reasons

A rule refusal arrives as {"error":"rejected","refusal":{"kind":"…"}} with status 409. Refusals common to all endpoints are in the rules section.

Code	What happened and what to do
`url`	The delivery address is invalid: the refusal carries a reason code — https only, a public host only, no username or password inside the address.
`no_events`	Tick at least one event: a subscription to nothing would look alive and stay silent.
`vault_off`	The marketplace vault is not configured, so there is nowhere to keep secrets. That is our problem, not yours: contact support.

Nearby in this section

GET /api/v1/hooks — My event subscription
DELETE /api/v1/hooks — Turn delivery off
POST /api/v1/hooks/secret — Rotate the signing secret
POST /api/v1/hooks/resume — Turn delivery back on
POST /api/v1/hooks/test — A test event
GET /api/v1/hooks/deliveries — The delivery log
POST /api/v1/hooks/probe — Issue a test receiver address
GET /api/v1/hooks/probe — What the test receiver got