API reference

Webhooks

Endpoints that receive signed event notifications.

List webhook endpoints GET /v1/webhooks
Create a webhook endpoint POST /v1/webhooks
Delete a webhook endpoint DELETE /v1/webhooks/{id}

List webhook endpoints

GET/v1/webhooks

Requires a secret key with the read scope.

Request

curl "https://api.newhost.co.za/v1/webhooks" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": [
    {
      "id": "clx8whk0001",
      "url": "https://example.com/hooks/newhost",
      "description": "Order system",
      "events": [
        "deployment.succeeded",
        "deployment.failed"
      ],
      "active": true,
      "createdAt": "2026-09-10T12:00:00.000Z"
    }
  ],
  "has_more": false
}

Create a webhook endpoint

POST/v1/webhooks

The signing secret is returned once. Use it to verify the NewHost-Signature header.

Requires a secret key with the write scope. Returns 201 on success.

Body

Field	Type	Description
`url`required	string	Public https:// URL.
`events`	string[]	Event types, or ["*"] for all (default).
`description`	string	Shown in the dashboard.

Request

curl -X POST "https://api.newhost.co.za/v1/webhooks" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/newhost","events":["deployment.succeeded","deployment.failed"],"description":"Order system"}'

Response

{
  "data": {
    "id": "clx8whk0001",
    "url": "https://example.com/hooks/newhost",
    "description": "Order system",
    "events": [
      "deployment.succeeded",
      "deployment.failed"
    ],
    "active": true,
    "createdAt": "2026-09-10T12:00:00.000Z",
    "secret": "whsec_3f9d…"
  }
}

Delete a webhook endpoint

DELETE/v1/webhooks/{id}

Requires a secret key with the write scope.

Parameters

Name	In	Type	Description
`id`required	path	string	The webhook ID.

Request

curl -X DELETE "https://api.newhost.co.za/v1/webhooks/ID" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "id": "clx8whk0001",
    "deleted": true
  }
}

Next: AI gateway →