Unstoppable Finance (Iron) Webhooks API

openapi: 3.2.0
info:
  description: The Stablecoin Payment Network
  title: Iron API - Sandbox Webhooks API
  version: 1.0-16988
servers:
- url: https://api.sandbox.iron.xyz/api
tags:
- description: Operations on Webhooks
  name: Webhooks
paths:
  /webhooks:
    get:
      description: 'Lists all webhooks for the currently authenticated partner

        '
      operationId: listWebhooks
      parameters:
      - deprecated: false
        description: 'Paging: the cursor field from previous page'
        explode: false
        in: query
        name: cursor
        required: false
        schema:
          default: null
          format: uuid
          type: string
      - deprecated: false
        description: 'Paging: the requested page size (max 100)'
        explode: false
        in: query
        name: page_size
        required: false
        schema:
          default: 10
          format: uint32
          type: integer
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/PagedList_Webhook'
          description: Listing successful
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: Unauthorized
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Failed to list webhooks
      security:
      - ApiKeyAuth: []
      summary: List all webhooks
      tags:
      - Webhooks
  /webhooks/{id}:
    patch:
      description: 'Updates an existing webhook for the currently authenticated partner

        '
      operationId: updateWebhook
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the webhook will be updated under scope of the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: The ID of the webhook to update
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
        description: The webhook update request
        required: true
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Webhook'
          description: Update successful
        '400':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: Bad request (e.g. invalid data)
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: Unauthorized
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: Not Found
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Failed to update the webhook
      security:
      - ApiKeyAuth: []
      summary: Update a webhook
      tags:
      - Webhooks
  /webhooks/{id}/ping:
    post:
      description: Sends a test ping event to a webhook for testing purposes
      operationId: pingWebhook
      parameters:
      - deprecated: false
        description: a UUID ensuring the ping operation is only processed once
        explode: true
        in: header
        name: IDEMPOTENCY-KEY
        required: true
        schema:
          type: string
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the webhook will be pinged under scope of the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: the ID of the webhook to ping
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/PingWebhookParams'
        description: Parameters required to ping a webhook
        required: true
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                type: boolean
          description: Successfully pinged webhook
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: Unauthorized
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: Webhook not found
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      summary: Ping webhook
      tags:
      - Webhooks
webhooks:
  new_event:
    post:
      description: 'This webhook is triggered when a significant event occurs within the system

        that a partner might be interested in. The payload contains details about the

        event type and the associated data.


        ## Request


        The webhook will be sent as an HTTP `POST` request to the URL configured

        for the webhook. The body of the request will be a JSON payload

        (`application/json`) containing an `ApiWebhookContainer`.


        ## Headers


        The following headers will be included in the request, adhering to [the

        Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md):


        - `content-type: application/json`: Indicates the payload format.

        - `webhook-id`: A unique UUID (version 4) identifying this specific

        delivery attempt. This can be used for idempotency and logging.

        - `webhook-timestamp`: A string representing the Unix timestamp (seconds since epoch)

        of when the webhook notification was sent.

        - `webhook-signature`: A signature to verify the authenticity and integrity

        of the payload. The format is `v1=<signature>`, where `<signature>` is

        an HMAC-SHA256 hash.


        ## Signature Verification


        To verify the signature:

        1. Extract the `webhook-timestamp` from the header.

        2. Extract the `webhook-signature` from the header and remove the `v1=` prefix.

        3. Concatenate the `webhook-timestamp` string and the raw request body.

        4. Calculate the HMAC-SHA256 hash of the concatenated string using your

        webhook''s secret key.

        5. Compare the calculated hash (hex-encoded) with the signature extracted

        from the header. They should match.


        It is crucial to use a constant-time comparison function when comparing

        signatures to prevent timing attacks.

        (See the examples for more details)'
      operationId: newEvent
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/WebhookContainer'
        required: true
      responses:
        '200':
          description: ''
      summary: Dispatches an event notification to a configured webhook endpoint.
      tags:
      - Webhooks
components:
  schemas:
    CustomerStatus:
      description: 'The status of the Customer

        '
      enum:
      - UserRequired
      - SigningsRequired
      - IdentificationRequired
      - Active
      - Suspended
      - Archived
      type: string
    PagedList_Webhook:
      description: 'PagedList


        A list of items with cursors used to fetch the next or previous page

        '
      properties:
        cursor:
          description: The cursor used to fetch the next page
          format: uuid
          type: string
        items:
          description: The list of items
          items:
            $ref: '#/components/schemas/Webhook'
          type: array
        prev_cursor:
          default: null
          description: The cursor used to fetch the previous page
          format: uuid
          type: string
      required:
      - items
      title: PagedList_Webhook
      type: object
    AutorampTransactionStatus:
      description: 'Autoramp Transaction Status


        The status of the autoramp transaction

        '
      enum:
      - FundsReviewInProgress
      - ConversionInProgress
      - PayoutInProgress
      - Completed
      - Failed
      - RejectedAml
      - RejectedFraud
      - RejectedMinAmount
      type: string
    WebhookEventMessage:
      description: 'Webhook Event Message


        Contains details about a general event notification

        '
      properties:
        id:
          description: Unique identifier for the event
          format: uuid
          type: string
        kind:
          $ref: '#/components/schemas/WebhookEventKind'
      required:
      - id
      - kind
      title: WebhookEventMessage
      type: object
    WebhookEventType:
      description: 'Webhook Event Types


        Represents the different types of webhook events that can be sent

        '
      enum:
      - Transaction
      - NewBankAccount
      - NewAutoramp
      - DepositAddressCreated
      - RegisterFiatAddressStatus
      - RegisterAutorampStatus
      - TransactionStatus
      - CustomerCreated
      - CustomerStatus
      - IdentificationStatus
      - Ping
      type: string
    WebhookTransactionStatusMessage:
      description: 'Webhook Transaction Status Message


        Contains details about a transaction status change

        '
      properties:
        id:
          description: Unique identifier for the transaction
          format: uuid
          type: string
        status:
          allOf:
          - $ref: '#/components/schemas/AutorampTransactionState'
          - deprecated: true
            description: 'Current status of the transaction. DEPRECATED: use ''transaction_status'''
          deprecated: true
          description: 'Current status of the transaction. DEPRECATED: use ''transaction_status'''
        transaction_hash:
          description: The blockchain transaction hash for crypto payouts (when available)
          type: string
        transaction_status:
          $ref: '#/components/schemas/AutorampTransactionStatus'
      required:
      - id
      - status
      - transaction_status
      title: WebhookTransactionStatusMessage
      type: object
    IdentificationStatus:
      description: 'The Process status of the identification


        The various state transitions an identification can go through.

        '
      enum:
      - Pending
      - Processed
      - PendingReview
      - Approved
      - Declined
      - Expired
      - Archived
      type: string
    PingWebhookParams:
      properties:
        customer_id:
          description: Customer ID to use for the webhook ping
          format: uuid
          type: string
      required:
      - customer_id
      title: PingWebhookParams
      type: object
    UpdateWebhookRequest:
      description: 'Update Webhook Request


        Request to update an existing webhook

        '
      properties:
        enabled:
          description: Optional enabled status
          type: boolean
        label:
          description: Optional new label for the webhook
          type: string
        topics:
          description: Optional new topics for the webhook
          items:
            $ref: '#/components/schemas/WebhookEventType'
          type: array
        url:
          description: Optional new URL for the webhook
          type: string
      title: UpdateWebhookRequest
      type: object
    WebhookContainer:
      description: 'Webhook Container


        Top-level container for webhook notifications

        '
      properties:
        data:
          $ref: '#/components/schemas/WebhookNotification'
        timestamp:
          description: ISO timestamp when the notification was sent
          type: string
        type:
          description: The type of notification
          type: string
      required:
      - type
      - timestamp
      - data
      title: WebhookContainer
      type: object
    WebhookCustomerStatusMessage:
      description: 'Webhook Customer Status Message


        Contains details about a customer status change

        '
      properties:
        id:
          description: Unique identifier for the customer
          format: uuid
          type: string
        status:
          $ref: '#/components/schemas/CustomerStatus'
      required:
      - id
      - status
      title: WebhookCustomerStatusMessage
      type: object
    WebhookMessage:
      anyOf:
      - $ref: '#/components/schemas/WebhookEventMessage'
      - $ref: '#/components/schemas/WebhookFiatAddressStatusMessage'
      - $ref: '#/components/schemas/WebhookAutorampStatusMessage'
      - $ref: '#/components/schemas/WebhookTransactionStatusMessage'
      - $ref: '#/components/schemas/WebhookCustomerStatusMessage'
      - $ref: '#/components/schemas/WebhookIdentificationStatusMessage'
      - $ref: '#/components/schemas/WebhookPingMessage'
      description: 'Webhook Message


        Union type representing different kinds of webhook messages

        '
      type: object
    AutorampStatus:
      enum:
      - Created
      - EditPending
      - Authorized
      - DepositAccountAdded
      - Approved
      - Rejected
      - Cancelled
      type: string
    AutorampTransactionState:
      description: 'Autoramp Transaction State


        The state of the autoramp transaction

        '
      enum:
      - Pending
      - PayoutPending
      - Payout
      - PayoutCompleted
      - Completed
      - Failed
      - InAmlReview
      - AmlRejected
      - AmountRejected
      - FraudRejected
      type: string
    FiatAddressStatus:
      description: 'Verification Status


        The status of the verification of a fiat address

        '
      enum:
      - AuthorizationRequired
      - AuthorizationFailed
      - RegistrationPending
      - RegistrationFailed
      - Registered
      type: string
    WebhookPingMessage:
      description: 'Webhook Ping Message


        A test message sent to verify webhook functionality

        '
      properties:
        id:
          description: Unique identifier for the ping message
          format: uuid
          type: string
      required:
      - id
      title: WebhookPingMessage
      type: object
    Webhook:
      description: 'Webhook


        Response containing webhook details

        '
      properties:
        created_at:
          description: When the webhook was created
          format: date-time
          type: string
        enabled:
          description: Whether the webhook is enabled
          type: boolean
        id:
          description: The ID of the webhook
          format: uuid
          type: string
        label:
          description: A descriptive label for the webhook
          type: string
        last_failure:
          description: The last time the webhook was executed with an error
          format: date-time
          type: string
        last_failure_reason:
          description: The reason for the last failure
          type: string
        partner_id:
          description: The partner ID that owns this webhook
          format: uuid
          type: string
        topics:
          description: The topics this webhook subscribes to
          items:
            $ref: '#/components/schemas/WebhookEventType'
          type: array
        updated_at:
          description: When the webhook was last updated
          format: date-time
          type: string
        url:
          description: The URL to send webhook events to
          type: string
      required:
      - id
      - label
      - url
      - partner_id
      - topics
      - created_at
      - updated_at
      - enabled
      title: Webhook
      type: object
    WebhookFiatAddressStatusMessage:
      description: 'Webhook Fiat Address Status Message


        Contains details about a fiat address status change

        '
      properties:
        id:
          description: Unique identifier for the fiat address
          format: uuid
          type: string
        status:
          $ref: '#/components/schemas/FiatAddressStatus'
      required:
      - id
      - status
      title: WebhookFiatAddressStatusMessage
      type: object
    WebhookAutorampStatusMessage:
      description: 'Webhook Autoramp Status Message


        Contains details about an autoramp status change

        '
      properties:
        id:
          description: Unique identifier for the autoramp
          format: uuid
          type: string
        status:
          $ref: '#/components/schemas/AutorampStatus'
      required:
      - id
      - status
      title: WebhookAutorampStatusMessage
      type: object
    WebhookNotification:
      description: 'Webhook Notification


        Notification sent to a webhook subscriber containing event details

        '
      properties:
        customer_id:
          description: The ID of the customer associated with this notification
          format: uuid
          type: string
        message:
          $ref: '#/components/schemas/WebhookMessage'
      required:
      - customer_id
      - message
      title: WebhookNotification
      type: object
    ApiError:
      description: 'Standard error response returned to API clients for server errors.

        Includes a trace_id that clients can reference when reporting issues.'
      properties:
        message:
          description: Human-readable error message
          type: string
        trace_id:
          description: Trace ID that can be used to look up request details in logs
          type: string
      required:
      - message
      - trace_id
      title: ApiError
      type: object
    WebhookEventKind:
      description: 'Webhook Event Kind


        Types of events that can be included in webhook notifications

        '
      enum:
      - Transaction
      - NewBankAccount
      - NewAutoramp
      - DepositAddressCreated
      - CustomerCreated
      type: string
    WebhookIdentificationStatusMessage:
      description: 'Webhook Identification Status Message


        Contains details about an identification status change

        '
      properties:
        id:
          description: Unique identifier for the identification
          format: uuid
          type: string
        status:
          $ref: '#/components/schemas/IdentificationStatus'
      required:
      - id
      - status
      title: WebhookIdentificationStatusMessage
      type: object
  parameters:
    XApiVersion:
      description: 'Selects the API version for this request, as an ISO date (`YYYY-MM-DD`). Omit to use the default version (`2025-03-13`). Supported versions: 2025-03-13, 2026-07-01.'
      in: header
      name: X-API-Version
      required: false
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      description: API Key
      in: header
      name: X-API-Key
      type: apiKey