BTCPay Server Webhooks API

openapi: 3.2.0
info:
  title: BTCPay Greenfield Webhooks API
  version: v1
  description: '# Introduction


    The BTCPay Server Greenfield API is a REST API.'
  contact:
    name: BTCPay Server
    url: https://btcpayserver.org
  license:
    name: MIT
    url: https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE
servers:
- url: https://{btcpay-host}
  description: Your BTCPay Server instance
  variables:
    btcpay-host:
      default: mainnet.demo.btcpayserver.org
      description: The hostname of your BTCPay Server instance
security:
- API_Key: []
  Basic: []
tags:
- name: Webhooks
  description: Webhook operations
paths:
  /api/v1/stores/{storeId}/webhooks:
    parameters:
    - $ref: '#/components/parameters/StoreId'
    get:
      tags:
      - Webhooks
      summary: Get webhooks of a store
      description: View webhooks of a store
      operationId: Webhooks_GetWebhooks
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDataList'
        '404':
          description: The key is not found for this list of webhooks
      security:
      - API_Key:
        - btcpay.store.webhooks.canmodifywebhooks
        Basic: []
    post:
      operationId: Webhooks_CreateWebhook
      tags:
      - Webhooks
      summary: Create a new webhook
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookDataCreate'
        required: true
        x-position: 1
      responses:
        '200':
          description: Information about the new webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDataCreateResult'
        '400':
          description: A list of errors that occurred when creating the webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
      security:
      - API_Key:
        - btcpay.store.webhooks.canmodifywebhooks
        Basic: []
  /api/v1/webhooks/{webhookId}:
    parameters:
    - $ref: '#/components/parameters/WebhookId'
    get:
      tags:
      - Webhooks
      summary: Get a webhook
      description: View webhook
      operationId: Webhooks_GetWebhook
      responses:
        '200':
          description: A webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookData'
        '404':
          description: The webhook has not been found
      security:
      - API_Key:
        - btcpay.store.webhooks.canmodifywebhooks
        Basic: []
    put:
      operationId: Webhooks_UpdateWebhook
      tags:
      - Webhooks
      summary: Update a webhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookDataUpdate'
        required: true
        x-position: 1
      responses:
        '200':
          description: Information about the updated webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookData'
        '400':
          description: A list of errors that occurred when creating the webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
      security:
      - API_Key:
        - btcpay.store.webhooks.canmodifywebhooks
        Basic: []
    delete:
      operationId: Webhooks_DeleteWebhook
      tags:
      - Webhooks
      summary: Delete a webhook
      responses:
        '200':
          description: The webhook has been deleted
        '404':
          description: The webhook does not exist
      security:
      - API_Key:
        - btcpay.store.webhooks.canmodifywebhooks
        Basic: []
  /api/v1/webhooks/{webhookId}/deliveries:
    parameters:
    - $ref: '#/components/parameters/WebhookId'
    get:
      operationId: Webhooks_GetWebhookDeliveries
      tags:
      - Webhooks
      summary: Get latest deliveries
      description: List the latest deliveries to the webhook, ordered from the most recent
      parameters:
      - name: count
        in: query
        description: The number of latest deliveries to fetch
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List of deliveries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveryList'
        '404':
          description: The key is not found for this list of deliveries
      security:
      - API_Key:
        - btcpay.store.webhooks.canmodifywebhooks
        Basic: []
  /api/v1/webhooks/{webhookId}/deliveries/{deliveryId}:
    parameters:
    - $ref: '#/components/parameters/WebhookId'
    - $ref: '#/components/parameters/DeliveryId'
    get:
      operationId: Webhooks_GetWebhookDelivery
      tags:
      - Webhooks
      summary: Get a webhook delivery
      description: Information about a webhook delivery
      responses:
        '200':
          description: Information about a delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveryData'
        '404':
          description: The delivery does not exist.
      security:
      - API_Key:
        - btcpay.store.webhooks.canmodifywebhooks
        Basic: []
  /api/v1/webhooks/{webhookId}/deliveries/{deliveryId}/request:
    parameters:
    - $ref: '#/components/parameters/WebhookId'
    - $ref: '#/components/parameters/DeliveryId'
    get:
      operationId: Webhooks_GetWebhookDeliveryRequests
      tags:
      - Webhooks
      summary: Get the delivery's request
      description: The delivery's JSON request sent to the endpoint
      responses:
        '200':
          description: The delivery's JSON Request
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: The delivery does not exist.
        '409':
          description: '`webhookdelivery-pruned`: This webhook delivery has been pruned, so it can''t be redelivered.'
      security:
      - API_Key:
        - btcpay.store.webhooks.canmodifywebhooks
        Basic: []
  /api/v1/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver:
    parameters:
    - $ref: '#/components/parameters/WebhookId'
    - $ref: '#/components/parameters/DeliveryId'
    post:
      operationId: Webhooks_RedeliverWebhookDelivery
      tags:
      - Webhooks
      summary: Redeliver the delivery
      responses:
        '200':
          description: The new delivery id being broadcasted. (Broadcast happens asynchronously with this call)
          content:
            application/json:
              schema:
                type: string
        '404':
          description: The delivery does not exist.
        '409':
          description: '`webhookdelivery-pruned`: This webhook delivery has been pruned, so it can''t be redelivered.'
      security:
      - API_Key:
        - btcpay.store.webhooks.canmodifywebhooks
        Basic: []
components:
  schemas:
    WebhookDataBase:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type: boolean
          description: Whether this webhook is enabled or not
          default: true
        automaticRedelivery:
          type: boolean
          description: If true, BTCPay Server will retry to redeliver any failed delivery after 10 seconds, 1 minutes and up to 6 times after 10 minutes.
          default: true
        url:
          type: string
          description: The endpoint where BTCPay Server will make the POST request with the webhook body
        authorizedEvents:
          type: object
          description: Which event should be received by this endpoint
          properties:
            everything:
              type: boolean
              description: If true, the endpoint will receive all events related to the store.
              default: true
            specificEvents:
              type: array
              items:
                type: string
              description: 'If `everything` is false, the specific events that the endpoint is interested in. Current events are: `InvoiceCreated`, `InvoiceReceivedPayment`, `InvoiceProcessing`, `InvoiceExpired`, `InvoiceSettled`, `InvoiceInvalid`, `InvoicePaymentSettled`, `PaymentRequestCreated`, `PaymentRequestUpdated`, `PaymentRequestArchived`, `PaymentRequestStatusChanged`, `PayoutCreated`, `PayoutApproved`, `PayoutUpdated`, `SubscriberCreated`, `SubscriberCredited`, `SubscriberCharged`, `SubscriberActivated`, `SubscriberPhaseChanged`, `SubscriberDisabled`, `PaymentReminder`, `PlanStarted`, `SubscriberNeedUpgrade`.'
    WebhookDataCreate:
      allOf:
      - $ref: '#/components/schemas/WebhookDataBase'
      - type: object
        properties:
          secret:
            type:
            - string
            - 'null'
            description: Must be used by the callback receiver to ensure the delivery comes from BTCPay Server. BTCPay Server includes the `BTCPay-Sig` HTTP header, whose format is `sha256=HMAC256(UTF8(webhook's secret), body)`. The pattern to authenticate the webhook is similar to [how to secure webhooks in Github](https://docs.github.com/webhooks/securing/). If left out, null, or empty, the secret will be auto-generated.
    WebhookDataUpdate:
      allOf:
      - $ref: '#/components/schemas/WebhookDataBase'
      - type: object
        properties:
          secret:
            type:
            - string
            - 'null'
            description: Must be used by the callback receiver to ensure the delivery comes from BTCPay Server. BTCPay Server includes the `BTCPay-Sig` HTTP header, whose format is `sha256=HMAC256(UTF8(webhook's secret), body)`. The pattern to authenticate the webhook is similar to [how to secure webhooks in Github](https://docs.github.com/webhooks/securing/). If left out, null, or empty, the secret will not be changed.
    WebhookDeliveryData:
      type: object
      properties:
        id:
          type: string
          description: The id of the delivery
        timestamp:
          type: number
          description: Timestamp of when the delivery should have been broadcasted
          allOf:
          - $ref: '#/components/schemas/UnixTimestamp'
        deliveryTime:
          type: number
          description: Timestamp of when the delivery has actually been broadcasted. A delay with `timestamp` means your service either failed to process earlier deliveries or is taking too long to respond.
          allOf:
          - $ref: '#/components/schemas/UnixTimestamp'
        httpCode:
          type:
          - number
          - 'null'
          description: HTTP code received by the remote service, if any.
        errorMessage:
          type: string
          description: User friendly error message, if any.
        status:
          type: string
          description: 'Whether the delivery failed or not (possible values are: `Failed`, `HttpError`, `HttpSuccess`)'
    ValidationProblemDetails:
      type: array
      description: An array of validation errors of the request
      items:
        type: object
        description: A specific validation error on a json property
        properties:
          path:
            type: string
            description: The json path of the property which failed validation
          message:
            type: string
            description: User friendly error message about the validation
    UnixTimestamp:
      type: number
      format: int32
      example: 1592312018
      description: A unix timestamp in seconds
    WebhookDataList:
      type: array
      items:
        $ref: '#/components/schemas/WebhookData'
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
    WebhookDeliveryList:
      type: array
      items:
        $ref: '#/components/schemas/WebhookDeliveryData'
    WebhookData:
      allOf:
      - type: object
        properties:
          id:
            type: string
            description: The id of the webhook
      - $ref: '#/components/schemas/WebhookDataBase'
    WebhookDataCreateResult:
      allOf:
      - $ref: '#/components/schemas/WebhookData'
      - type: object
        properties:
          secret:
            type:
            - string
            - 'null'
            description: Must be used by the callback receiver to ensure the delivery comes from BTCPay Server. BTCPay Server includes the `BTCPay-Sig` HTTP header, whose format is `sha256=HMAC256(UTF8(webhook's secret), body)`. The pattern to authenticate the webhook is similar to [how to secure webhooks in Github](https://docs.github.com/webhooks/securing/). Value of the auto-generated or custom secret.
  parameters:
    StoreId:
      name: storeId
      in: path
      required: true
      description: The store ID
      schema:
        $ref: '#/components/schemas/StoreId'
    WebhookId:
      name: webhookId
      in: path
      required: true
      description: The webhook id
      schema:
        type: string
    DeliveryId:
      name: deliveryId
      in: path
      required: true
      description: The id of the delivery
      schema:
        type: string
  securitySchemes:
    API_Key:
      type: apiKey
      in: header
      name: Authorization
      description: 'BTCPay Server API key. Format: ''token {apiKey}'''
    Basic:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with email and password
externalDocs:
  description: Check out our examples on how to use the API
  url: https://docs.btcpayserver.org/Development/GreenFieldExample/