Webhooks

Manage webhook subscriptions — the HTTPS endpoints we deliver event notifications to. For the delivery format and verification, see Webhooks overview.

• GET /api/v1/webhooks — list

• POST /api/v1/webhooks — create

• GET /api/v1/webhooks/{id} — retrieve

• PATCH /api/v1/webhooks/{id} — update

• DELETE /api/v1/webhooks/{id} — remove

All endpoints require the admin scope.

---

GET /api/v1/webhooks

List webhook subscriptions in this tenant. Secrets are never returned by list/retrieve endpoints — only POST returns the secret, and only once.

Response 200

{
  "data": [
    {
      "id": "whs_01H...",
      "url": "https://hooks.acme.com/peak",
      "events": ["order.created", "subscription.changed"],
      "isActive": true,
      "createdAt": "2026-05-02T14:01:23Z"
    }
  ],
  "nextActions": [
    { "rel": "create", "method": "POST", "href": "/api/v1/webhooks" }
  ]
}

cURL

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/webhooks

---

POST /api/v1/webhooks

Create a webhook subscription. The response includes a secret; copy it now — it cannot be retrieved later.

Body

Field	Type	Required	Description
url	string (URL)	yes	https:// only, and not a private or loopback address — see What we accept as a destination URL
events	string[] (≥1)	yes	Event types to subscribe to

Response 201

{
  "data": {
    "id": "whs_01H...",
    "url": "https://hooks.acme.com/peak",
    "events": ["order.created", "subscription.changed"],
    "isActive": true,
    "secret": "whsec_82ab...c4f9",
    "createdAt": "2026-05-02T14:01:23Z"
  },
  "nextActions": [
    { "rel": "self", "method": "GET", "href": "/api/v1/webhooks/whs_01H..." },
    { "rel": "update", "method": "PATCH", "href": "/api/v1/webhooks/whs_01H..." },
    { "rel": "delete", "method": "DELETE", "href": "/api/v1/webhooks/whs_01H..." }
  ]
}

Errors

Status	When
400	Validation failed — url is not https://, points at a private or loopback address, or events is empty. The message names which

cURL

curl -X POST https://api.example.com/api/v1/webhooks \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.acme.com/peak",
    "events": ["order.created", "subscription.changed", "payment.succeeded"]
  }'

---

GET /api/v1/webhooks/{id}

Retrieve a webhook subscription (without secret).

Response 200

Same shape as the list rows.

Errors

Status	When
404	Not found

cURL

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/webhooks/whs_01H...

---

PATCH /api/v1/webhooks/{id}

Update a webhook subscription.

Body (all optional)

Field	Type	Description
url	string (URL)	Replace destination URL. Held to the same rules as create — an existing subscription cannot be edited into an http:// or private-address endpoint
events	string[]	Replace subscribed events
isActive	boolean	Disable without deleting

Response 200

Same shape as GET.

Errors

Status	When
400	Validation failed — including a url that is not https:// or points at a private or loopback address
404	Not found

cURL

curl -X PATCH https://api.example.com/api/v1/webhooks/whs_01H... \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'

---

DELETE /api/v1/webhooks/{id}

Permanently delete a webhook subscription. Pending retries are cancelled.

Response 204

Empty body.

Errors

Status	When
404	Not found

cURL

curl -X DELETE https://api.example.com/api/v1/webhooks/whs_01H... \
  -H "Authorization: Bearer $PEAK_API_KEY"

---

What we accept as a destination URL

Applies to POST /api/v1/webhooks and to PATCH when it changes url.

https:// is required. Plain http:// is rejected with 400. A webhook payload is signed, but a signature only proves who sent it — it does not stop anything on the path from reading it, and these payloads carry order, subscription and contact data. If your test environment has no certificate, use a tunnelling service that terminates TLS for you rather than an http:// endpoint.

The destination must be publicly routable. We refuse addresses that would make our servers call into a private network:

Refused	Examples
loopback and unspecified	localhost, 127.0.0.0/8, 0.0.0.0, ::1
RFC 1918 private ranges	10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12 (i.e. 172.16.x through 172.31.x)
link-local, incl. cloud metadata	169.254.0.0/16, which covers 169.254.169.254

This is a check on the address you give us, not on where a hostname resolves: a public DNS name that points at a private address is something we cannot see, so treat this as a guard rather than a guarantee.

Related

• Webhooks overview

• Webhooks (admin app: Settings → Developer Tools → Webhooks)