---
title: "Webhooks — API reference"
description: "Signed HTTPS callbacks for service, invoice, order and ticket events."
url: https://www.gyrohosting.com/developers/en/api/webhooks.html
language: en
openapi: https://www.gyrohosting.com/developers/openapi.json
api_version: 2.30.0
---

# Webhooks

Signed HTTPS callbacks for service, invoice, order and ticket events.

Base URL: `https://www.gyrohosting.com/api/v1/client` · OpenAPI: https://www.gyrohosting.com/developers/openapi.json


## GET /cloud/webhooks

**List webhooks** · operationId `listWebhooks` · scope `webhooks` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/listWebhooks.json




### Responses

- **200**: Webhooks

### Examples

```bash
curl -s 'https://www.gyrohosting.com/api/v1/client/cloud/webhooks' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro webhook list
```
```hcl
# resource gyro_webhook: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/resources/webhook
resource "gyro_webhook" "ops" {
  url    = "https://hooks.example.com/gyro"
  events = ["service.active", "service.suspended", "invoice.paid"]
}

output "webhook_secret" {
  value     = gyro_webhook.ops.secret
  sensitive = true
}
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/webhooks", headers=h, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/webhooks", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
  },
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## POST /cloud/webhooks

**Create a webhook (secret returned once)** · operationId `createWebhook` · scope `webhooks` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/createWebhook.json

Deliveries are `POST` JSON with headers `X-Gyro-Event`, `X-Gyro-Delivery`, `X-Gyro-Timestamp` and
`X-Gyro-Signature: sha256=HMAC_SHA256(secret, timestamp + "." + body)` (white-label resellers: `X-Webhook-*`).
Reject requests whose timestamp is older than 5 minutes. Retries: exponential back-off, 8 attempts; 20 consecutive failures disable the webhook.



### Request body

| Field | Type | Description |
|---|---|---|
| `url` (required) | string |  |
| `events` | array<WebhookEvent> | empty = all |
| `description` | string |  |
| `customer_id` | integer | Reseller main key only |

### Responses

- **201**: Created (includes secret)
- **422**: Validation or business rule failure (`confirm_required`, `invalid_image`, `tool_action_failed` ...)

### Examples

```bash
curl -s -X POST 'https://www.gyrohosting.com/api/v1/client/cloud/webhooks' \
  -H "Authorization: Bearer $GYRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/gyro", "events": ["service.active", "invoice.paid"]}'
```
```bash
gyro webhook create --help    # all flags
```
```hcl
# resource gyro_webhook: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/resources/webhook
resource "gyro_webhook" "ops" {
  url    = "https://hooks.example.com/gyro"
  events = ["service.active", "service.suspended", "invoice.paid"]
}

output "webhook_secret" {
  value     = gyro_webhook.ops.secret
  sensitive = true
}
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.post("https://www.gyrohosting.com/api/v1/client/cloud/webhooks", headers=h, json={"url": "https://hooks.example.com/gyro", "events": ["service.active", "invoice.paid"]}, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/webhooks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"url": "https://hooks.example.com/gyro", "events": ["service.active", "invoice.paid"]}),
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## GET /cloud/webhooks/{id}

**Get a webhook** · operationId `getWebhook` · scope `webhooks` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/getWebhook.json




### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer |  |

### Responses

- **200**: Webhook
- **404**: Not found — also returned for objects owned by someone else

### Examples

```bash
curl -s 'https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro webhook get 12345
```
```hcl
# resource gyro_webhook: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/resources/webhook
resource "gyro_webhook" "ops" {
  url    = "https://hooks.example.com/gyro"
  events = ["service.active", "service.suspended", "invoice.paid"]
}

output "webhook_secret" {
  value     = gyro_webhook.ops.secret
  sensitive = true
}
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345", headers=h, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
  },
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## PATCH /cloud/webhooks/{id}

**Update url, events, description or status** · operationId `updateWebhook` · scope `webhooks` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/updateWebhook.json




### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer |  |

### Request body

| Field | Type | Description |
|---|---|---|
| `url` | string |  |
| `events` | array<WebhookEvent> |  |
| `description` | string |  |
| `status` | string (active, disabled) |  |

### Responses

- **200**: Webhook
- **404**: Not found — also returned for objects owned by someone else
- **422**: Validation or business rule failure (`confirm_required`, `invalid_image`, `tool_action_failed` ...)

### Examples

```bash
curl -s -X PATCH 'https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345' \
  -H "Authorization: Bearer $GYRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "string", "events": ["service.created"], "description": "string", "status": "active"}'
```
```bash
gyro webhook update 12345 --help    # all flags
```
```hcl
# resource gyro_webhook: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/resources/webhook
resource "gyro_webhook" "ops" {
  url    = "https://hooks.example.com/gyro"
  events = ["service.active", "service.suspended", "invoice.paid"]
}

output "webhook_secret" {
  value     = gyro_webhook.ops.secret
  sensitive = true
}
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.patch("https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345", headers=h, json={"url": "string", "events": ["service.created"], "description": "string", "status": "active"}, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345", {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"url": "string", "events": ["service.created"], "description": "string", "status": "active"}),
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## DELETE /cloud/webhooks/{id}

**Delete a webhook** · operationId `deleteWebhook` · scope `webhooks` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/deleteWebhook.json




### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer |  |

### Responses

- **200**: Deleted
- **404**: Not found — also returned for objects owned by someone else

### Examples

```bash
curl -s -X DELETE 'https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro webhook delete 12345
```
```hcl
# resource gyro_webhook: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/resources/webhook
resource "gyro_webhook" "ops" {
  url    = "https://hooks.example.com/gyro"
  events = ["service.active", "service.suspended", "invoice.paid"]
}

output "webhook_secret" {
  value     = gyro_webhook.ops.secret
  sensitive = true
}
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.delete("https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345", headers=h, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345", {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
  },
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## POST /cloud/webhooks/{id}/test

**Send an api.test event now** · operationId `testWebhook` · scope `webhooks` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/testWebhook.json




### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer |  |

### Responses

- **200**: Result
- **404**: Not found — also returned for objects owned by someone else

### Examples

```bash
curl -s -X POST 'https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345/test' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro webhook test 12345
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.post("https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345/test", headers=h, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345/test", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
  },
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## GET /cloud/webhooks/{id}/deliveries

**Last 100 deliveries** · operationId `listWebhookDeliveries` · scope `webhooks` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/listWebhookDeliveries.json




### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer |  |

### Responses

- **200**: Deliveries
- **404**: Not found — also returned for objects owned by someone else

### Examples

```bash
curl -s 'https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345/deliveries' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro webhook delivery list 12345
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345/deliveries", headers=h, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/webhooks/12345/deliveries", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
  },
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```