Webhooks

Updated Oct 4, 2026 Markdown

GET /api/v1/system/webhooks

List webhook endpoints

Return every registered webhook subscriber.

Responses:

Status Schema Description
200 ApiSuccess_list_dict_str__Any___ Successful Response

Response example (200):

JSON
{
  "data": [
    {}
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks

POST /api/v1/system/webhooks

Create webhook endpoint

Register a new subscriber. The plaintext secret is returned ONLY on this response; rotate via /rotate to mint a new one.

Body fields:

Field Type Required Notes
description string no default ``
enabled boolean no default True
events array no —
secret string no —
url string yes —

Request body example:

JSON
{
  "description": "",
  "enabled": true,
  "events": [
    "string"
  ],
  "secret": "string",
  "url": "string"
}

Responses:

Status Schema Description
200 ApiSuccess_dict_str__Any__ Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/system/webhooks

GET /api/v1/system/webhooks/deliveries

List webhook deliveries

Paginated history of delivery attempts (success, failed, dead-letter).

Query parameters:

Name Type Required Notes
limit integer no minimum=1; maximum=500
offset integer no minimum=0
endpoint_id string no —
status string no —
event_type string no —

Responses:

Status Schema Description
200 ApiSuccess_dict_str__Any__ Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/deliveries

GET /api/v1/system/webhooks/deliveries/{delivery_id}

Get delivery detail

Return the full record (payload + response excerpt) for a single delivery attempt.

Path parameters:

Name Type Required Notes
delivery_id string yes pattern=^dlv_[a-f0-9]+$

Responses:

Status Schema Description
200 ApiSuccess_dict_str__Any__ Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/deliveries/{delivery_id}

POST /api/v1/system/webhooks/deliveries/{delivery_id}/retry

Retry delivery

Re-enqueue a failed / dead-letter delivery at its own endpoint. A new delivery id is minted and the original record stays for audit; 404 when the endpoint is gone, 409 WEBHOOK_DISABLED while it is disabled or muted.

Path parameters:

Name Type Required Notes
delivery_id string yes pattern=^dlv_[a-f0-9]+$

Responses:

Status Schema Description
200 ApiSuccess_dict_str__Any__ Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/deliveries/{delivery_id}/retry

GET /api/v1/system/webhooks/events

List webhook event types

Return the catalog of every event a webhook endpoint can subscribe to.

Responses:

Status Schema Description
200 ApiSuccess_list_dict_str__Any___ Successful Response

Response example (200):

JSON
{
  "data": [
    {}
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/events

DELETE /api/v1/system/webhooks/{endpoint_id}

Delete webhook endpoint

Permanently remove a subscriber. Pending queued events for this endpoint are dropped on the next dispatcher tick.

Path parameters:

Name Type Required Notes
endpoint_id string yes pattern=^whk_[a-f0-9]+$

Responses:

Status Schema Description
200 MessageResponse Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "message": "string",
  "status": "success"
}

cURL example:

shell
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/{endpoint_id}

GET /api/v1/system/webhooks/{endpoint_id}

Get webhook endpoint

Fetch a single endpoint by id. The secret is masked.

Path parameters:

Name Type Required Notes
endpoint_id string yes pattern=^whk_[a-f0-9]+$

Responses:

Status Schema Description
200 ApiSuccess_dict_str__Any__ Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/{endpoint_id}

PUT /api/v1/system/webhooks/{endpoint_id}

Update webhook endpoint

Update url, events, description, enabled flag, or mute window. Pass secret only when explicitly rotating.

Path parameters:

Name Type Required Notes
endpoint_id string yes pattern=^whk_[a-f0-9]+$

Body fields:

Field Type Required Notes
description string no —
enabled boolean no —
events array no —
muted_until string no —
secret string no —
url string no —

Request body example:

JSON
{
  "description": "string",
  "enabled": false,
  "events": [
    "string"
  ],
  "muted_until": "string",
  "secret": "string",
  "url": "string"
}

Responses:

Status Schema Description
200 ApiSuccess_dict_str__Any__ Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X PUT \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/system/webhooks/{endpoint_id}

POST /api/v1/system/webhooks/{endpoint_id}/rotate

Rotate webhook secret

Generate a new HMAC secret. The plaintext value is returned ONCE — store it on the subscriber immediately.

Path parameters:

Name Type Required Notes
endpoint_id string yes pattern=^whk_[a-f0-9]+$

Responses:

Status Schema Description
200 ApiSuccess_dict_str__Any__ Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/{endpoint_id}/rotate

POST /api/v1/system/webhooks/{endpoint_id}/test

Send test event

Enqueue a synthetic event addressed at this endpoint only (other subscribers of the same event do not receive it). A disabled or muted endpoint answers 409 WEBHOOK_DISABLED. Useful for confirming connectivity + signature validation on the subscriber side.

Path parameters:

Name Type Required Notes
endpoint_id string yes pattern=^whk_[a-f0-9]+$

Responses:

Status Schema Description
200 ApiSuccess_dict_str__Any__ Successful Response
422 HTTPValidationError Validation Error

Response example (200):

JSON
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/{endpoint_id}/test
Still Need Help?

Our support team is here around the clock for anything you can't find above.

Contact Us Open a Ticket