---
title: "Subscribe a callback URL to dispatch lifecycle events"
method: POST
path: "/api/v1/webhooks/subscriptions"
---

# Subscribe a callback URL to dispatch lifecycle events

`POST /api/v1/webhooks/subscriptions`

## Request

- Base URL: `https://scope.bid`
- URL: `https://scope.bid/api/v1/webhooks/subscriptions`
- Auth: HTTP bearer

HTTPS callback. Returns the signing secret once. Deliveries carry X-Scope-Signature (v1=HMAC_SHA256(secret, timestamp + '.' + body)), X-Scope-Event-Id (idempotency), X-Scope-Timestamp. The body is { id, type, occurred_at, tenant_id, scope_id, data }. For type 'dispatch.pending_approval', data carries scope_id, display_id, approval_id, triggered_rules, computed_price_cents (the professional's price), vendor_id (the professional's organization) and auto_escalate_after_minutes. Beside the professional's price, five fields say what the firm will be billed if it approves. firm_total_cents (integer or null): the estimated firm total, the professional's price plus Scope's fee line, computed with the invoice's own arithmetic on the terms on file now; null when Scope cannot determine the fee before the job is sent. scope_fee_cents (integer or null): Scope's fee line as it would be billed; null when firm_total_cents is null. scope_fee_label (string): the invoice line Scope's fee appears under, "Service coordination and compliance record". firm_total_is_estimate (boolean or null): true whenever firm_total_cents is a number, because the amount billed is set when the job is sent (for example, the professional's current rates apply then); null when firm_total_cents is null. billing_note (string): one sentence for a person: the estimated firm total with the invoice's two lines and why it can move; or the professional's price and the sentence that Scope's fee is added on the invoice; or, when Scope could not read the price, that sentence alone. These fields describe the bill; they do not change what is approved or sent.

## Response `201`

Created; secret returned once.

## Other responses

- `400`: callback_url required / must be https.

---

[API](https://skmtc.dev/scope/apis/scope-api.md) · [All operations](https://skmtc.dev/scope/apis/scope-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scope/apis/scope-api/revisions/164347b416ac?raw)