Blackbaud Subscriptions API

openapi: 3.2.0
info:
  title: 'Blackbaud SKY API: Webhook Subscriptions API'
  description: This API provides Webhook capabilities for the SKY Developer platform.
  version: v1
  x-apievangelist-provenance:
    source: https://developer.sky.blackbaud.com/developer/apis/webhook
    method: assembled from Blackbaud's public API Management developer data API (operations, parameters, representations, examples, stored definitions); nothing authored
    assembled: '2026-10-14'
servers:
- url: https://api.sky.blackbaud.com/webhook
security:
- Bb-Api-Subscription-Key: []
  OAuth2: []
tags:
- name: Subscriptions
paths:
  /subscriptions:
    post:
      operationId: CreateSubscription
      summary: Create a subscription
      description: Creates a subscription in your application. This subscription is scoped to the Blackbaud Environment authorized by your SKY API access token.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
            example:
              webhook_url: https://example.org/skyapi/webhook/handler?key=sHTZC6xX>&A<(*eR7:D!:jF7(65K@wgk
              event_type: com.blackbaud.constituent.delete.v1
        description: The body of the request. Contains the details for a new subscription request.
      responses:
        '200':
          description: Returned when the operation succeeds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCreated'
              example:
                id: eb42ba64-2712-4232-b69b-caed6b6d6fdd
                provisioning_status: Provisioning
        '400':
          description: Returned when the specified request parameters are not provided.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CreateSubscriptionBadRequestResponse'
              example:
                type: urn:blackbaud:invalid-address-type
                title: One or more validation errors occurred.
                status: 400
                detail: The type Home is not valid for this address.
                values:
                  type: Home
                trace_id: 0092384aa2c24842a550a0137bbf3172
                span_id: f7c9d108335d479588f5f165ca17a5e3
        '403':
          description: Returned when the application does not have sufficient permissions to create the subscription for the event type requested.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: urn:blackbaud:forbidden
                title: The requested action is forbidden.
                status: 403
                detail: This application has insufficient scope to create the subscription for the event type requested.
        '409':
          description: Returned when the subscription you want to create has already been created.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: urn:blackbaud:conflict
                title: The request failed conflict validation.
                status: 409
                trace_id: 0092384aa2c24842a550a0137bbf3172
                span_id: f7c9d108335d479588f5f165ca17a5e3
      tags:
      - Subscriptions
    get:
      operationId: GetSubscriptionList
      summary: Get subscription list
      description: Returns a list of subscriptions for your application. These subscriptions are scoped to the Blackbaud Environment authorized by your SKY API access token.
      responses:
        '200':
          description: Returned when the operation succeeds. The response body contains the list of subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriptions'
              example:
                value:
                - id: eb42ba64-2712-4232-b69b-caed6b6d6fdd
                  environment_id: p-vnVAbDtfu0GyMqSDmG-_qw
                  webhook_url: https://example.org/skyapi/webhook/handler
                  application_id: 90caa693-b36e-4eea-942d-fb813e36ceb7
                  event_type: com.blackbaud.constituent.email.change.v1
                  provisioning_status: Pending
                - id: 259d1af0-6594-4f34-bb51-54bff66ec704
                  environment_id: p-vnVAbDtfu0GyMqSDmG-_qw
                  webhook_url: https://example.org/skyapi/webhook/handler2
                  application_id: 90caa693-b36e-4eea-942d-fb813e36ceb7
                  event_type: com.blackbaud.constituent.email.change.v1
                  provisioning_status: Provisioned
                count: 2
        '400':
          description: Returned when the specified request parameters are not provided.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ModelValidationProblemDetails'
              example:
                type: urn:blackbaud:model-validation-error
                title: One or more validation errors occurred.
                status: 400
                detail: The date field is required.
                trace_id: 0092384aa2c24842a550a0137bbf3172
                span_id: f7c9d108335d479588f5f165ca17a5e3
      tags:
      - Subscriptions
  /subscriptions/{subscription_id}:
    get:
      operationId: GetSubscription
      summary: Get a subscription
      description: Returns subscription information for a specific application and subscription ID. The subscription is scoped to the Blackbaud Environment authorized by your SKY API access token.
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
        description: The ID for the subscription.
      responses:
        '200':
          description: Returned when the operation succeeds. The response body contains the subscription information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
              example:
                id: eb42ba64-2712-4232-b69b-caed6b6d6fdd
                environment_id: p-vnVAbDtfu0GyMqSDmG-_qw
                webhook_url: https://example.org/skyapi/webhook/handler
                application_id: 90caa693-b36e-4eea-942d-fb813e36ceb7
                event_type: com.blackbaud.constituent.email.change.v1
                provisioning_status: Pending
        '404':
          description: Returned when no subscription exists in your application for the subscription ID provided.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: urn:blackbaud:resource-not-found
                title: The requested resource could not be found.
                status: 404
                trace_id: 0092384aa2c24842a550a0137bbf3172
                span_id: f7c9d108335d479588f5f165ca17a5e3
        '400':
          description: Returned when the specified request parameters are not provided.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/GetSubscriptionBadRequestResponse'
              example:
                type: urn:blackbaud:invalid-address-type
                title: One or more validation errors occurred.
                status: 400
                detail: The type Home is not valid for this address.
                values:
                  type: Home
                trace_id: 0092384aa2c24842a550a0137bbf3172
                span_id: f7c9d108335d479588f5f165ca17a5e3
      tags:
      - Subscriptions
    delete:
      operationId: DeleteSubscription
      summary: Remove a subscription
      description: Removes a subscription in your application. The subscription removed is scoped to the Blackbaud Environment authorized by your SKY API access token.
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
        description: The ID for the subscription.
      responses:
        '200':
          description: Returned when the operation succeeds.
        '400':
          description: Returned when the specified request parameters are not provided.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/DeleteSubscriptionBadRequestResponse'
              example:
                type: urn:blackbaud:subscription-is-provisioning
                title: One or more validation errors occurred.
                status: 400
                detail: This operation cannot be done while the subscription is Provisioning. Please wait for subscription to provision. If stuck, the subscription can be deleted after 30 minutes regardless of provisioning state.
        '404':
          description: Returned when no subscription exists in your application for the subscription ID provided.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: urn:blackbaud:resource-not-found
                title: The requested resource could not be found.
                status: 404
                trace_id: 0092384aa2c24842a550a0137bbf3172
                span_id: f7c9d108335d479588f5f165ca17a5e3
        '409':
          description: Returned when the subscription's state doesn't allow it to be deleted.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: urn:blackbaud:conflict
                title: The request failed conflict validation.
                status: 409
                trace_id: 0092384aa2c24842a550a0137bbf3172
                span_id: f7c9d108335d479588f5f165ca17a5e3
      tags:
      - Subscriptions
components:
  schemas:
    Subscription:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Subscription ID
        environment_id:
          type:
          - string
          - 'null'
          description: Environment ID
        webhook_url:
          type:
          - string
          - 'null'
          description: Subscription webhook url
        application_id:
          type:
          - string
          - 'null'
          description: Application ID
        event_type:
          type:
          - string
          - 'null'
          description: Event type
        provisioning_status:
          $ref: '#/components/schemas/ProvisioningStatus'
      additionalProperties: false
      description: Webhook subscription
    GetSubscriptionBadRequestResponse:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".<br/><br/>Available values:<table><tr><th>type</th><th>detail</th></tr><tr><td>urn:blackbaud:model-validation-error</td><td>A model validation rule was violated, such as a missing required field.</td></tr><tr><td>urn:blackbaud:invalid-event-type</td><td>{0} is not a valid event type</td></tr></table>
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        trace_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
        span_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
      additionalProperties: {}
      description: A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807.
      x-bb-error-types:
      - urn:blackbaud:model-validation-error
      - urn:blackbaud:invalid-event-type
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        trace_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
        span_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
      additionalProperties: {}
      description: A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807.
    CreateSubscriptionBadRequestResponse:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".<br/><br/>Available values:<table><tr><th>type</th><th>detail</th></tr><tr><td>urn:blackbaud:model-validation-error</td><td>A model validation rule was violated, such as a missing required field.</td></tr><tr><td>urn:blackbaud:invalid-event-type</td><td>{0} is not a valid event type</td></tr><tr><td>urn:blackbaud:app-max-subscriptions-count</td><td>The application {0} is limited to {1} subscriptions per environment {2}</td></tr><tr><td>urn:blackbaud:webhook-url-invalid</td><td>The webhook URL is invalid</td></tr><tr><td>urn:blackbaud:webhook-url-invalid-format</td><td>The webhook URL is not properly formatted and fully qualified. The URL scheme (HTTPS) must be specified.</td></tr><tr><td>urn:blackbaud:webhook-url-invalid-schema</td><td>The webhook URL is not HTTPS</td></tr><tr><td>urn:blackbaud:webhook-url-handshake-missing-origin-header</td><td>Received an unexpected 'WebHook-Allowed-Origin' header value from your webhook URL when performing the CloudEvent's Abuse Protection handshake. The header must equal 'eventgrid.azure.net'. Review our Webhook API documentation to learn more. https://developer.blackbaud.com/skyapi/apis/webhook</td></tr><tr><td>urn:blackbaud:webhook-url-handshake-invalid-status-code</td><td>Received an invalid HTTPS status code from your webhook URL when performing the CloudEvent's Abuse Protection handshake with your webhook URL. Review our Webhook API documentation to learn more. https://developer.blackbaud.com/skyapi/apis/webhook</td></tr><tr><td>urn:blackbaud:webhook-url-unreachable</td><td>We were unable to reach the specified webhook URL. Please check the URL and try again.</td></tr><tr><td>urn:blackbaud:webhook-event-timeout</td><td>Your webhook failed to respond in 30 seconds to the test event payload. A webhook must respond to webhook events within 30 seconds. After 30 seconds, we will terminate the event request and retry later with exponential backoff (up to 9 times).</td></tr><tr><td>urn:blackbaud:webhook-event-terminated</td><td>The connection to your webhook was unexpectedly terminated during the request.</td></tr></table>
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        trace_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
        span_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
      additionalProperties: {}
      description: A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807.
      x-bb-error-types:
      - urn:blackbaud:model-validation-error
      - urn:blackbaud:invalid-event-type
      - urn:blackbaud:app-max-subscriptions-count
      - urn:blackbaud:webhook-url-invalid
      - urn:blackbaud:webhook-url-invalid-format
      - urn:blackbaud:webhook-url-invalid-schema
      - urn:blackbaud:webhook-url-handshake-missing-origin-header
      - urn:blackbaud:webhook-url-handshake-invalid-status-code
      - urn:blackbaud:webhook-url-unreachable
      - urn:blackbaud:webhook-event-timeout
      - urn:blackbaud:webhook-event-terminated
    DeleteSubscriptionBadRequestResponse:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".<br/><br/>Available values:<table><tr><th>type</th><th>detail</th></tr><tr><td>urn:blackbaud:model-validation-error</td><td>A model validation rule was violated, such as a missing required field.</td></tr><tr><td>urn:blackbaud:subscription-is-provisioning</td><td>This operation cannot be done while the subscription is Provisioning. Please wait for subscription to provision. If stuck, the subscription can be deleted after 30 minutes regardless of provisioning state.</td></tr></table>
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        trace_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
        span_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
      additionalProperties: {}
      description: A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807.
      x-bb-error-types:
      - urn:blackbaud:model-validation-error
      - urn:blackbaud:subscription-is-provisioning
    ProvisioningStatus:
      title: ProvisioningStatus
      enum:
      - Pending
      - Provisioning
      - Provisioned
      - Error
      type: string
      description: Provisioning status
    SubscriptionRequest:
      required:
      - event_type
      - webhook_url
      type: object
      properties:
        webhook_url:
          minLength: 1
          type: string
          description: The Webhook URL for the subscription.
        event_type:
          minLength: 1
          type: string
          description: The event type for the subscription.
      additionalProperties: false
      description: The request for the Webhook subscription.
    SubscriptionCreated:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Subscription ID
        provisioning_status:
          $ref: '#/components/schemas/ProvisioningStatus'
      additionalProperties: false
      description: Subscription created
    ModelValidationProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".<br/><br/>Available values:<table><tr><th>type</th><th>detail</th></tr><tr><td>urn:blackbaud:model-validation-error</td><td>A model validation rule was violated, such as a missing required field.</td></tr></table>
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        trace_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
        span_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
      additionalProperties: {}
      description: A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807.
      x-bb-error-types:
      - urn:blackbaud:model-validation-error
    Subscriptions:
      type: object
      properties:
        value:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Subscription'
          description: The subscriptions
        count:
          type: integer
          description: Count of subscriptions
          format: int32
      additionalProperties: false
      description: A collection of Webhook subscriptions
  securitySchemes:
    Bb-Api-Subscription-Key:
      type: apiKey
      name: Bb-Api-Subscription-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.blackbaud.com/oauth/authorize
          tokenUrl: https://oauth2.sky.blackbaud.com/token
          scopes: {}