scope-bid Webhooks API

openapi: 3.2.0
info:
  title: Scope Bid Webhooks API
  version: 1.1.0
  description: 'Operations tagged Webhooks across 2 of this provider''s published API definitions: scope-bid-openapi.json, scope-bid-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://scope.bid
  description: Production
security:
- bearerAuth: []
tags:
- name: Webhooks
paths:
  /api/v1/webhooks/subscriptions:
    post:
      summary: Subscribe a callback URL to dispatch lifecycle events
      description: '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.'
      responses:
        '201':
          description: Created; secret returned once.
        '400':
          description: callback_url required / must be https.
      tags:
      - Webhooks
      operationId: postApiV1WebhooksSubscriptions
      x-operation-id-source: derived
    get:
      summary: List this firm's webhook subscriptions
      responses:
        '200':
          description: Subscriptions.
      tags:
      - Webhooks
      operationId: getApiV1WebhooksSubscriptions
      x-operation-id-source: derived
    delete:
      summary: Revoke a subscription
      description: A partner token needs the read or govern scope and revokes only the subscriptions that partner created. A firm caller (session or PAT) needs settings.write or must be a firm admin. Revoking a subscription that is already revoked answers 200.
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Revoked.
        '400':
          description: id is required.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'No subscription with this id at this firm (for a partner: none it created), including an id that is not a uuid. Nothing was revoked.'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Database error. Nothing was revoked.
        '503':
          description: Scope could not confirm the caller's role at the firm. Nothing was revoked. Retry.
      tags:
      - Webhooks
      operationId: deleteApiV1WebhooksSubscriptions
      x-operation-id-source: derived
    servers:
    - url: https://scope.bid
      description: Production
  /api/v1/webhooks/subscriptions/{id}/test:
    post:
      summary: Send a test event to verify signature handling
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Test event enqueued.
        '404':
          description: Subscription not found.
      tags:
      - Webhooks
      operationId: postApiV1WebhooksSubscriptionsByIdTest
      x-operation-id-source: derived
    servers:
    - url: https://scope.bid
      description: Production
components:
  responses:
    Forbidden:
      description: 'The caller is not authorized: the caller''s role does not grant the required capability, the partner token lacks the required scope, or the partner is not authorized to act for this firm.'
    Unauthorized:
      description: Missing or invalid access token.
    RateLimited:
      description: Per-tenant rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds until the window resets.
          schema:
            type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'OAuth 2.0 access token, or a personal access token (PAT) for CI and power users. Pass as Authorization: Bearer <token>. Every token resolves to exactly one tenant.'
x-refined-from:
- scope-bid-openapi.json
- scope-bid-openapi.json