> For the complete documentation index, see [llms.txt](https://docs.scaleconnect.com.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleconnect.com.au/api/webhooks/subscriptions.md).

# Subscriptions

{% @scale-docs-page-title/page-title title="Subscriptions" %}

{% hint style="warning" %}
**Confirm before publishing:** the subscription routes, request and response DTOs, URL verification handshake, signing-secret return, event allowlist, update/pause behaviour, delivery-history retention and permissions. These are designed `/v1/integrators` routes; no public subscription API has been verified in production.
{% endhint %}

A webhook subscription binds one HTTPS endpoint to a set of approved public [event types](/api/webhooks/events.md). Create one subscription per receiver when you need separate secrets, permissions or failure monitoring.

## Register a callback

```http
POST /v1/integrators/webhooks HTTP/1.1
Authorization: Bearer sc_live_<secret>
Content-Type: application/json

{
  "url": "https://example.invalid/scale/webhooks",
  "events": ["client.created", "client.updated"],
  "description": "CRM client sync"
}
```

The create response should return the subscription ID and signing secret **once**. Store the secret securely, then confirm that the receiver verifies a signed delivery. The registration design checks that the URL answers a validation ping with 2xx; an unreachable URL returns `422`. Unknown, internal or unauthorized event names return `400`.

## Manage a subscription

| Method   | Path                                                          | Purpose                                  | Scope            |
| -------- | ------------------------------------------------------------- | ---------------------------------------- | ---------------- |
| `POST`   | `/v1/integrators/webhooks`                                    | Create subscription                      | `webhooks:write` |
| `GET`    | `/v1/integrators/webhooks`                                    | List subscriptions                       | `webhooks:read`  |
| `GET`    | `/v1/integrators/webhooks/{id}`                               | Inspect one                              | `webhooks:read`  |
| `DELETE` | `/v1/integrators/webhooks/{id}`                               | Remove it                                | `webhooks:write` |
| `GET`    | `/v1/integrators/webhooks/{id}/deliveries`                    | Inspect attempts; filter `status=failed` | `webhooks:read`  |
| `POST`   | `/v1/integrators/webhooks/{id}/deliveries/{deliveryId}/retry` | Replay the stored event                  | `webhooks:write` |
| `POST`   | `/v1/integrators/webhooks/{id}/rotate-secret`                 | Issue a new signing secret               | `webhooks:write` |

The final generated operation reference must define exact status codes, pagination, validation errors and response bodies for each row.

## Rotation and recovery

When rotating the signing secret, update the receiver before the old secret expires. The proposed overlap is 24 hours. A replay uses the original event body and event ID; your receiver must deduplicate it just like an ordinary retry. If a delivery repeatedly fails, fix the endpoint and replay from delivery history rather than creating a second subscription for the same event.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.scaleconnect.com.au/api/webhooks/subscriptions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.