> Documentation index: https://docs.sellhidden.com/llms.txt

# Webhooks

Source: https://docs.sellhidden.com/reference/webhooks

Manage the endpoints that receive signed events (the same ones as Developers, Webhooks). The signing secret is returned once, on create and on rotate.

## Endpoints

8 endpoints · [webhooks:read](https://docs.sellhidden.com/start?scope=webhooks%3Aread#scopes) · [webhooks:write](https://docs.sellhidden.com/start?scope=webhooks%3Awrite#scopes)

Base URL https://api.sellhidden.com/v1 · Authorization: Bearer · 120/min per key · cursor pagination · Idempotency-Key on POST · No test mode

### GET /webhooks — List endpoints

Scope `webhooks:read`.

```bash
curl https://api.sellhidden.com/v1/webhooks \
  -H "Authorization: Bearer hsk_live_…"
```

Response (200):

```json
{ "ok": true, "webhooks": [ { "id": "clx…", "url": "https://example.com/hooks", "label": "Fulfilment", "events": [ "order.paid" ], "active": true, "consecutiveFailures": 0, "secretHint": "whsec_1a2b…", "lastDelivery": { … }, "deliveryCount": 42, "createdAt": "…" } ], "limit": 5 }
```

### POST /webhooks — Create an endpoint

Public https URLs only. Counts against the plan's endpoint limit (403 plan_limit). Scope `webhooks:write`. Accepts `Idempotency-Key`. Returns 201.

**Body**

| Body | Type | Description |
| --- | --- | --- |
| `url` (required) | string | https URL. |
| `events` (required) | string[] | Event names (see Webhooks, Events), or wildcards like order.* or *. |
| `label` | string | Up to 60 characters. |

```bash
curl -X POST https://api.sellhidden.com/v1/webhooks \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://example.com/hooks/hidden",
    "events": [
      "order.paid",
      "order.delivered"
    ],
    "label": "Fulfilment"
  }'
```

Response (201):

```json
{ "ok": true, "webhook": { "id": "clx…", "url": "…", "events": [ "order.paid", "order.delivered" ], "active": true, "secret": "whsec_…", … } }
```

### GET /webhooks/{id} — Get an endpoint

Scope `webhooks:read`.

```bash
curl https://api.sellhidden.com/v1/webhooks/ID \
  -H "Authorization: Bearer hsk_live_…"
```

### PATCH /webhooks/{id} — Update an endpoint

Scope `webhooks:write`.

**Body**

| Body | Type | Description |
| --- | --- | --- |
| `url` | string |  |
| `label` | string |  |
| `events` | string[] |  |
| `active` | boolean | Switch it on again after it was disabled for failures. |
| `resetFailures` | boolean | Reset the consecutive failure counter. |

```bash
curl -X PATCH https://api.sellhidden.com/v1/webhooks/ID \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"active":true,"resetFailures":true}'
```

### DELETE /webhooks/{id} — Delete an endpoint

Scope `webhooks:write`.

```bash
curl -X DELETE https://api.sellhidden.com/v1/webhooks/ID \
  -H "Authorization: Bearer hsk_live_…"
```

### POST /webhooks/{id}/rotate-secret — Rotate the secret

Returns the new secret once. Deliveries are signed with it from now on. Scope `webhooks:write`. Accepts `Idempotency-Key`.

```bash
curl -X POST \
  https://api.sellhidden.com/v1/webhooks/ID/rotate-secret \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Idempotency-Key: $(uuidgen)"
```

### POST /webhooks/{id}/test — Send a test event

A signed webhook.test delivery (10 per endpoint per minute). The response carries the delivery row with the status code your endpoint returned. Scope `webhooks:write`.

```bash
curl -X POST \
  https://api.sellhidden.com/v1/webhooks/ID/test \
  -H "Authorization: Bearer hsk_live_…"
```

### GET /webhooks/{id}/deliveries — Delivery log

Scope `webhooks:read`.

**Query parameters**

| Query parameters | Type | Description |
| --- | --- | --- |
| `status` | ok \| failed |  |
| `limit` | 1..100 | Page size. Default 25. |
| `cursor` | string | nextCursor from the previous page. |

```bash
curl https://api.sellhidden.com/v1/webhooks/ID/deliveries \
  -H "Authorization: Bearer hsk_live_…"
```