sochain-com Webhooks API

openapi: 3.2.0
info:
  title: Sochain Com Webhooks API
  version: '3'
  description: 'Operations tagged Webhooks across 3 of this provider''s published API definitions: sochain-com-openapi.json, dev-sochain-com-openapi.json, sochain-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://sochain.com/api/v3
- url: https://dev.sochain.com/api/v3
security:
- ApiKey: []
- ApiKeyQuery: []
tags:
- name: Webhooks
paths:
  /webhooks:
    get:
      operationId: list_webhooks
      tags:
      - Webhooks
      summary: List your webhooks
      description: 'Webhooks per plan: Free 5 (testnets only), Hobby 10, Starter 100, Professional 5,000, Behemoth 25,000.'
      parameters: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    const: success
                  data:
                    $ref: '#/components/schemas/WebhookList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/Unavailable'
      externalDocs:
        url: https://sochain.com/docs/webhooks/api
    post:
      operationId: create_webhook
      tags:
      - Webhooks
      summary: Create a webhook
      description: Each notification counts as one request; retries don't. Addresses watched by address webhooks and streams together, each counted once, are capped per plan (Free 500, Hobby 1,000, Starter 10,000, Professional 25,000, Behemoth 100,000; Free's on testnets); past that, 403.
      parameters: []
      security:
      - ApiKey: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    const: success
                  data:
                    $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/TooLarge'
        '415':
          $ref: '#/components/responses/NotJson'
        '503':
          $ref: '#/components/responses/Unavailable'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
            example:
              type: address.transaction
              network: BTC
              url: https://api.yourapp.com/hooks/deposits
              bucket: wallet1
              notify_at:
              - 0
              - 1
      externalDocs:
        url: https://sochain.com/docs/webhooks/api
    servers:
    - url: https://sochain.com/api/v3
  /webhooks/{id}:
    get:
      operationId: get_webhook
      tags:
      - Webhooks
      summary: One webhook
      description: ''
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    const: success
                  data:
                    $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/Unavailable'
      externalDocs:
        url: https://sochain.com/docs/webhooks/api
    patch:
      operationId: update_webhook
      tags:
      - Webhooks
      summary: Change a webhook
      description: Its url, label, notify_at or threshold, or pause and resume it (status). A new url is checked at once. Any other field is refused with a 400 that says where that change is made.
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      security:
      - ApiKey: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    const: success
                  data:
                    $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/TooLarge'
        '415':
          $ref: '#/components/responses/NotJson'
        '429':
          description: 'A new url within 10 seconds of the endpoint''s last check: wait the Retry-After seconds.'
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fail'
        '503':
          $ref: '#/components/responses/Unavailable'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdate'
      externalDocs:
        url: https://sochain.com/docs/webhooks/api
    delete:
      operationId: delete_webhook
      tags:
      - Webhooks
      summary: Remove a webhook
      description: ''
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      security:
      - ApiKey: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    const: success
                  data:
                    type: object
                    required:
                    - id
                    - deleted
                    properties:
                      id:
                        type: string
                      deleted:
                        const: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/Unavailable'
      externalDocs:
        url: https://sochain.com/docs/webhooks/api
    servers:
    - url: https://sochain.com/api/v3
  /webhooks/{id}/addresses:
    post:
      operationId: add_webhook_addresses
      tags:
      - Webhooks
      summary: Watch more addresses (bulk)
      description: ''
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      security:
      - ApiKey: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    const: success
                  data:
                    $ref: '#/components/schemas/WebhookAddressesAdded'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/TooLarge'
        '415':
          $ref: '#/components/responses/NotJson'
        '503':
          $ref: '#/components/responses/Unavailable'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressList'
      externalDocs:
        url: https://sochain.com/docs/webhooks/api
    delete:
      operationId: remove_webhook_addresses
      tags:
      - Webhooks
      summary: Stop watching addresses
      description: ''
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      security:
      - ApiKey: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    const: success
                  data:
                    $ref: '#/components/schemas/WebhookAddressesRemoved'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/TooLarge'
        '415':
          $ref: '#/components/responses/NotJson'
        '503':
          $ref: '#/components/responses/Unavailable'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressList'
      externalDocs:
        url: https://sochain.com/docs/webhooks/api
    servers:
    - url: https://sochain.com/api/v3
  /webhooks/{id}/transactions:
    post:
      operationId: add_webhook_transactions
      tags:
      - Webhooks
      summary: Register transactions to track
      description: For transaction.confirmation webhooks, up to 1,000 per call. The transactions your webhooks track at once, across all of them, are capped per plan (Free 500, Hobby 1,000, Starter 10,000, Professional 25,000, Behemoth 100,000; Free's on testnets; each stops counting once its last notify_at level is sent); past that, 403.
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      security:
      - ApiKey: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    const: success
                  data:
                    $ref: '#/components/schemas/WebhookTransactionsAdded'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/TooLarge'
        '415':
          $ref: '#/components/responses/NotJson'
        '503':
          $ref: '#/components/responses/Unavailable'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionList'
      externalDocs:
        url: https://sochain.com/docs/webhooks/api
    servers:
    - url: https://sochain.com/api/v3
  /webhooks/{id}/deliveries:
    get:
      operationId: list_webhook_deliveries
      tags:
      - Webhooks
      summary: Recent deliveries
      description: ''
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    const: success
                  data:
                    $ref: '#/components/schemas/Deliveries'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/Unavailable'
      externalDocs:
        url: https://sochain.com/docs/webhooks/api
    servers:
    - url: https://sochain.com/api/v3
  /webhooks/{id}/verify:
    post:
      operationId: verify_webhook
      tags:
      - Webhooks
      summary: Check a webhook's endpoint again
      description: Sends the webhook.verify challenge again; the answer's status and verify_error say how it went. Counts as one request; at most once every 10 seconds per webhook.
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      security:
      - ApiKey: []
      responses:
        '200':
          description: Checked.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    const: success
                  data:
                    $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: 'The endpoint was checked under 10 seconds ago: wait the Retry-After seconds.'
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fail'
        '503':
          $ref: '#/components/responses/Unavailable'
      externalDocs:
        url: https://sochain.com/docs/webhooks/api
    servers:
    - url: https://sochain.com/api/v3
components:
  schemas:
    WebhookAddressesAdded:
      type: object
      required:
      - id
      - added
      - num_addresses
      properties:
        id:
          type: string
        added:
          type: integer
          description: Addresses it didn't watch yet.
        num_addresses:
          type: integer
          description: Addresses it watches now.
    TransactionList:
      type: object
      required:
      - transactions
      properties:
        transactions:
          type: array
          minItems: 1
          items:
            type: string
            pattern: ^[0-9a-f]{64}$
          description: Transaction IDs to track.
    Deliveries:
      type: object
      description: 'Recent deliveries of this webhook: the event, the attempt count, and how your server answered.'
      required:
      - id
      - deliveries
      properties:
        id:
          type: string
          description: The webhook.
        deliveries:
          type: array
          items:
            type: object
    WebhookList:
      type: object
      required:
      - webhooks
      properties:
        webhooks:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
    WebhookType:
      enum:
      - address.transaction
      - transaction.confirmation
      - block.new
      - fees.below
      - fees.above
      description: block.reorged, transaction.replaced and transaction.dropped are delivered alongside these; they aren't created on their own.
    Fail:
      type: object
      required:
      - status
      - data
      properties:
        status:
          const: fail
        data:
          type: object
          required:
          - error_message
          properties:
            error_message:
              type: string
    BucketName:
      type: string
      pattern: ^[A-Za-z0-9_-]+$
      description: Letters, numbers, - and _, up to 64 characters. Unique within your account.
      maxLength: 64
    AddressList:
      type: object
      required:
      - addresses
      properties:
        addresses:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            type: string
    WebhookUpdate:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: 'A new endpoint: it''s checked at once, and the webhook is unverified until it echoes the challenge.'
        status:
          enum:
          - active
          - paused
          description: Pause it, or resume it (a webhook resumes once verified).
        label:
          type: string
          description: Yours, as the dashboard shows it.
        notify_at:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 100
          description: 'address.transaction and transaction.confirmation: as on create.'
        threshold:
          type: number
          exclusiveMinimum: 0
          description: 'fees.below and fees.above: the fee rate to cross; the alert starts over.'
      description: Any of these; what isn't sent stays as it is. Any other field is refused with a 400.
    WebhookAddressesRemoved:
      type: object
      required:
      - id
      - removed
      properties:
        id:
          type: string
        removed:
          type: integer
          description: Addresses it stopped watching.
    Webhook:
      type: object
      required:
      - id
      - type
      - network
      - url
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/WebhookType'
        network:
          enum:
          - BTC
          - LTC
          - DOGE
          - ZEC
          - BTCTEST
          - LTCTEST
          - DOGETEST
          - ZECTEST
        url:
          type: string
          format: uri
        bucket:
          type:
          - string
          - 'null'
        notify_at:
          type: array
          items:
            type: integer
        threshold:
          type:
          - number
          - 'null'
        label:
          type:
          - string
          - 'null'
          description: Yours, as the dashboard shows it.
        status:
          enum:
          - unverified
          - active
          - paused
        num_addresses:
          type: integer
          description: Addresses it watches itself (address.transaction without a bucket).
        num_transactions:
          type: integer
          description: Transactions it tracks (transaction.confirmation).
        created:
          type: integer
          description: When it was made (Unix time).
        last_event_at:
          type:
          - integer
          - 'null'
          description: When it last sent an event (Unix time); null before its first.
        failing_since:
          type:
          - integer
          - 'null'
          description: When its deliveries started failing (Unix time); null while they succeed.
        verified:
          type: boolean
        verify_error:
          type:
          - string
          - 'null'
          description: Why the last endpoint check failed, if it did.
        secret:
          type: string
          description: 'Only in the answer to POST /webhooks: the signing secret, shown once.'
    WebhookTransactionsAdded:
      type: object
      required:
      - id
      - added
      properties:
        id:
          type: string
        added:
          type: integer
          description: Transactions it didn't track yet.
    WebhookCreate:
      type: object
      required:
      - type
      - url
      properties:
        type:
          $ref: '#/components/schemas/WebhookType'
        network:
          enum:
          - BTC
          - LTC
          - DOGE
          - ZEC
          - BTCTEST
          - LTCTEST
          - DOGETEST
          - ZECTEST
          description: 'Required unless bucket is given. Free plans: BTCTEST, LTCTEST, DOGETEST or ZECTEST.'
        url:
          type: string
          format: uri
          description: Your HTTPS endpoint, on a public host (not sochain.com).
        bucket:
          $ref: '#/components/schemas/BucketName'
          description: 'address.transaction only: watch every address in this bucket.'
        addresses:
          type: array
          maxItems: 1000
          items:
            type: string
          description: 'address.transaction without a bucket: the addresses to watch, up to 1,000 in this call (add more with POST /webhooks/{id}/addresses).'
        transactions:
          type: array
          maxItems: 1000
          items:
            type: string
          description: 'transaction.confirmation: the transaction IDs to track, up to 1,000 in this call (add more with POST /webhooks/{id}/transactions).'
        notify_at:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 100
          description: 'Confirmation counts to notify at, from 0 (first seen) to 100; transaction.confirmation from 1. Defaults: [0, 1] for address.transaction, [1, 2, 3, 6] for transaction.confirmation.'
        label:
          type: string
          description: 'Optional, for you: shown on the dashboard.'
        threshold:
          type: number
          description: 'fees.below / fees.above: the fee rate (sat/vB, lit/vB or koinu/vB) to cross.'
  parameters:
    webhook_id:
      name: id
      in: path
      required: true
      description: The webhook's ID.
      schema:
        type: string
  responses:
    NotJson:
      description: 'A body that isn''t JSON: send it with Content-Type: application/json.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fail'
    TooLarge:
      description: 'A body over the limit: 256 KB where a call carries addresses or transaction IDs, 64 KB otherwise.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fail'
    BadRequest:
      description: A bad parameter or body; the message says which.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fail'
    Unauthorized:
      description: An invalid key, no key where one is needed (buckets, webhooks, /account_info), a locked account or expired plan, or both the month's requests and the keyless rate used up. Kept as 401, with this message, for v3 compatibility.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fail'
          example:
            status: fail
            data:
              error_message: API Key invalid, account access expired, or this account's daily request limit has been exhausted.
    Forbidden:
      description: 'A read-only key, or a change past your plan''s limits: data.error_message says which.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fail'
    Unavailable:
      description: Briefly unavailable; retry with backoff. May carry Retry-After.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fail'
          example:
            status: fail
            data:
              error_message: Temporarily unavailable. Try again in a few minutes.
    NotFound:
      description: Not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fail'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: API-KEY
      description: Your key, from the dashboard.
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Your key as a URL parameter, for lookups (GET) from tools that can't send a header, such as spreadsheets. Best a read-only key.
x-refined-from:
- sochain-com-openapi.json
- dev-sochain-com-openapi.json
- sochain-com-openapi.json