Register a webhook endpoint

POST

/webhooks

Registers a delivery endpoint and returns a secret that is shown only once — it signs every notification, so store it immediately. Lost it? Rotate to get a new one.

There may be at most two endpoints: one primary and one backup. If no role is given, the first free one is assigned. A third endpoint is rejected with 4090, a taken role with 4091.

URL requirements, validated on creation and on every edit: https only; the host must resolve to a public address — loopback, private RFC1918 ranges, link-local including 169.254.169.254 and other non-routable ranges are rejected; credentials in the URL are not allowed; length up to 2048 characters.

Authorizations

ApiKeyAuth

API key from the dashboard. Some Host Mode endpoints also accept the key as an api_key field in the request body — this is stated in the schema of the particular operation.

Type

API Key (header: X-API-KEY)

Parameters

Header Parameters

X-Real-IP*

An IP address from the key's whitelist. A request from an address outside the whitelist is rejected with 401.

Type

string

Required

Example"203.0.113.10"

Format

"ipv4"

Request Body

application/json

{

  

"url": "string",

  

"role": "string"

}

Responses

The endpoint was created. The secret in the response is shown only this once.

Content-Type

application/json

{

  

"detail": {

  

  

"code": 10000,

  

  

"status": "created",

  

  

"data": {

  

  

  

"id": 0,

  

  

  

"url": "string",

  

  

  

"role": "string",

  

  

  

"is_active": true,

  

  

  

"secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

  

  

  

"created_at": "string",

  

  

  

"updated_at": "string"

  

  

}

  

}

}

POST

/webhooks

Playground

Authorization

ApiKeyAuth

Headers

X-Real-IP*

Body

Samples

Powered by VitePress OpenAPI