Augustus Webhook Subscriptions API

openapi: 3.2.0
info:
  title: Augustus Banking Webhook Subscriptions API
  description: Augustus Banking API
  version: 0.1.0
  contact:
    name: Augustus
    url: https://docs.augustus.com
    email: developer@augustus.com
servers:
- url: https://api.augustus.com
  description: Production
- url: https://api.sandbox.augustus.com
  description: Sandbox
security:
- BearerAuth: []
tags:
- name: Webhook Subscriptions
paths:
  /v1/webhook_subscriptions:
    post:
      description: Creates a new webhook subscription.
      operationId: WebhookSubscriptionsController_create
      parameters:
      - name: Idempotency-Key
        in: header
        description: Idempotency key for safe retries. Reusing a key with an identical request body returns the cached response. Reusing a key with a different body returns 409.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: Webhook subscription creation parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookSubscriptionBodyDto'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionResourceDto'
      summary: Create webhook subscription
      tags:
      - Webhook Subscriptions
    get:
      description: Lists webhook subscriptions for the merchant with cursor-based pagination.
      operationId: WebhookSubscriptionsController_list
      parameters:
      - name: limit
        required: false
        in: query
        description: Number of results per page (1-100). Defaults to 10.
        schema:
          minimum: 1
          maximum: 100
          default: 10
          type: integer
      - name: cursor
        required: false
        in: query
        description: Opaque cursor from a previous next_cursor.
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of webhook subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWebhookSubscriptionsResponseDto'
      summary: List webhook subscriptions
      tags:
      - Webhook Subscriptions
  /v1/webhook_subscriptions/{id}:
    get:
      description: Retrieves a webhook subscription by ID.
      operationId: WebhookSubscriptionsController_retrieve
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the webhook subscription.
        schema:
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440009
          type: string
      responses:
        '200':
          description: The webhook subscription resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionResourceDto'
      summary: Retrieve webhook subscription
      tags:
      - Webhook Subscriptions
    post:
      description: Updates the URL and/or subscribed events.
      operationId: WebhookSubscriptionsController_update
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the webhook subscription.
        schema:
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440009
          type: string
      - name: Idempotency-Key
        in: header
        description: Idempotency key for safe retries. Reusing a key with an identical request body returns the cached response. Reusing a key with a different body returns 409.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: Fields to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookSubscriptionBodyDto'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionResourceDto'
      summary: Update webhook subscription
      tags:
      - Webhook Subscriptions
    delete:
      description: Permanently deletes a webhook subscription. This cannot be undone.
      operationId: WebhookSubscriptionsController_delete
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the webhook subscription.
        schema:
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440009
          type: string
      responses:
        '200':
          description: The deleted webhook subscription resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionResourceDto'
      summary: Delete webhook subscription
      tags:
      - Webhook Subscriptions
  /v1/webhook_subscriptions/{id}/send_test_event:
    post:
      description: Dispatches a signed `ping.test` event to this subscription's URL through the same pipeline as real events. Useful for verifying your receiver's reachability and signature verification in any environment without creating a real business event. Test-event failures do not affect the subscription's health counters or trigger failure-notification emails.
      operationId: WebhookSubscriptionsController_sendTestEvent
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the webhook subscription.
        schema:
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440009
          type: string
      - name: Idempotency-Key
        in: header
        description: Idempotency key for safe retries. Reusing a key with an identical request body returns the cached response. Reusing a key with a different body returns 409.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The newly created webhook event. Poll its delivery via `GET /v1/webhook_deliveries?event_id={id}` for receiver status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResourceDto'
      summary: Send test event
      tags:
      - Webhook Subscriptions
components:
  schemas:
    WebhookSubscriptionResourceDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the webhook subscription.
          example: 550e8400-e29b-41d4-a716-446655440009
        type:
          type: string
          description: Resource type discriminator.
          enum:
          - webhook_subscription
        url:
          type: string
          description: The HTTPS URL where webhook events are delivered.
          example: https://sandbox.example.com/webhooks/augustus
        events:
          type: array
          items:
            type: string
            enum:
            - payout.initiated
            - payout.submitted
            - payout.sent
            - payout.failed
            - payout.returned
            - return.initiated
            - return.submitted
            - return.sent
            - return.failed
            - return.returned
            - deposit.settled
            - conversion.created
            - conversion.completed
            - conversion.failed
            - account_holder.active
            - account_holder.closed
            - counterparty.pending
            - counterparty.active
            - counterparty.rejected
            - counterparty.blocked
            - counterparty.unblocked
            - counterparty.updated
            - payout_tracking_event.created
            description: Event type the subscription receives.
          description: Event types this subscription receives.
          example:
          - payout.sent
        metadata:
          type: object
          additionalProperties:
            type: string
            maxLength: 500
          description: Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.
          example:
            invoice_id: INV-2026-0042
        created_at:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the subscription was created.
          example: '2026-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the subscription was last updated.
          example: '2026-01-15T10:35:00Z'
      required:
      - id
      - type
      - url
      - events
      - metadata
      - created_at
      - updated_at
      additionalProperties: false
    EventResourceDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the event. Matches the envelope `id` delivered in the webhook payload and is stable across subscription fan-out and retries.
          example: 550e8400-e29b-41d4-a716-446655440008
        type:
          type: string
          description: Resource type discriminator.
          enum:
          - event
        event_type:
          type: string
          enum:
          - payout.initiated
          - payout.submitted
          - payout.sent
          - payout.failed
          - payout.returned
          - return.initiated
          - return.submitted
          - return.sent
          - return.failed
          - return.returned
          - deposit.settled
          - conversion.created
          - conversion.completed
          - conversion.failed
          - account_holder.active
          - account_holder.closed
          - counterparty.pending
          - counterparty.active
          - counterparty.rejected
          - counterparty.blocked
          - counterparty.unblocked
          - counterparty.updated
          - payout_tracking_event.created
          - ping.test
          description: Event type.
        api_version:
          type: string
          description: API version the event payload was rendered at. Stable across retries and redeliveries, and mirrored in the webhook envelope `api_version` field.
          example: '2026-05-01'
        created_at:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the event was created.
          example: '2026-01-15T10:30:00Z'
        data:
          type: object
          additionalProperties: {}
          description: Event payload. Shape matches the resource schema for `event_type`.
      required:
      - id
      - type
      - event_type
      - api_version
      - created_at
      - data
      additionalProperties: false
    ListWebhookSubscriptionsResponseDto:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Unique identifier of the webhook subscription.
                example: 550e8400-e29b-41d4-a716-446655440009
              type:
                type: string
                description: Resource type discriminator.
                enum:
                - webhook_subscription
              url:
                type: string
                description: The HTTPS URL where webhook events are delivered.
                example: https://sandbox.example.com/webhooks/augustus
              events:
                type: array
                items:
                  type: string
                  enum:
                  - payout.initiated
                  - payout.submitted
                  - payout.sent
                  - payout.failed
                  - payout.returned
                  - return.initiated
                  - return.submitted
                  - return.sent
                  - return.failed
                  - return.returned
                  - deposit.settled
                  - conversion.created
                  - conversion.completed
                  - conversion.failed
                  - account_holder.active
                  - account_holder.closed
                  - counterparty.pending
                  - counterparty.active
                  - counterparty.rejected
                  - counterparty.blocked
                  - counterparty.unblocked
                  - counterparty.updated
                  - payout_tracking_event.created
                  description: Event type the subscription receives.
                description: Event types this subscription receives.
                example:
                - payout.sent
              metadata:
                type: object
                additionalProperties:
                  type: string
                  maxLength: 500
                description: Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.
                example:
                  invoice_id: INV-2026-0042
              created_at:
                type: string
                format: date-time
                description: ISO 8601 UTC timestamp when the subscription was created.
                example: '2026-01-15T10:30:00Z'
              updated_at:
                type: string
                format: date-time
                description: ISO 8601 UTC timestamp when the subscription was last updated.
                example: '2026-01-15T10:35:00Z'
            required:
            - id
            - type
            - url
            - events
            - metadata
            - created_at
            - updated_at
            additionalProperties: false
        has_more:
          type: boolean
        next_cursor:
          type: string
          example: eyJsYXN0X2lkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDA2In0
          nullable: true
        has_previous:
          type: boolean
        previous_cursor:
          type: string
          example: eyJsYXN0X2lkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDA2In0
          nullable: true
      required:
      - data
      - has_more
      - next_cursor
      - has_previous
      - previous_cursor
      additionalProperties: false
    UpdateWebhookSubscriptionBodyDto:
      type: object
      properties:
        url:
          type: string
          format: uri
          pattern: ^https:\/\/.*
          description: The new HTTPS URL. Omit or send null to keep the current URL.
          example: https://sandbox.example.com/webhooks/augustus
          nullable: true
        events:
          minItems: 1
          type: array
          items:
            type: string
            enum:
            - payout.initiated
            - payout.submitted
            - payout.sent
            - payout.failed
            - payout.returned
            - return.initiated
            - return.submitted
            - return.sent
            - return.failed
            - return.returned
            - deposit.settled
            - conversion.created
            - conversion.completed
            - conversion.failed
            - account_holder.active
            - account_holder.closed
            - counterparty.pending
            - counterparty.active
            - counterparty.rejected
            - counterparty.blocked
            - counterparty.unblocked
            - counterparty.updated
            - payout_tracking_event.created
            - '*'
            description: Event type to subscribe to. Use "*" for all events.
          description: New event types. Omit or send null to keep the current events. Use ["*"] for all events.
          example:
          - payout.sent
          nullable: true
      additionalProperties: false
    CreateWebhookSubscriptionBodyDto:
      type: object
      properties:
        url:
          type: string
          format: uri
          pattern: ^https:\/\/.*
          description: The HTTPS URL where webhook events will be delivered.
          example: https://sandbox.example.com/webhooks/augustus
        events:
          minItems: 1
          type: array
          items:
            type: string
            enum:
            - payout.initiated
            - payout.submitted
            - payout.sent
            - payout.failed
            - payout.returned
            - return.initiated
            - return.submitted
            - return.sent
            - return.failed
            - return.returned
            - deposit.settled
            - conversion.created
            - conversion.completed
            - conversion.failed
            - account_holder.active
            - account_holder.closed
            - counterparty.pending
            - counterparty.active
            - counterparty.rejected
            - counterparty.blocked
            - counterparty.unblocked
            - counterparty.updated
            - payout_tracking_event.created
            - '*'
            description: Event type to subscribe to. Use "*" for all events.
          description: Event types to subscribe to. Use ["*"] for all events.
          example:
          - payout.sent
        metadata:
          type: object
          propertyNames:
            type: string
            maxLength: 40
          additionalProperties:
            type: string
            maxLength: 500
          description: Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.
          example:
            invoice_id: INV-2026-0042
          nullable: true
      required:
      - url
      - events
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Bearer token for authentication with Augustus Banking API
x-provenance:
  method: harvested
  publisher: Augustus
  source: https://api.augustus.com/openapi/2026-05-01.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)