asyncapi: 3.0.0
info:
  title: Balad Gateway Webhooks
  version: '2.0'
  description: >-
    Event-driven webhook surface for the Balad Gateway. Balad POSTs signed event envelopes to
    a partner-registered, whitelisted webhook URL when a transaction changes status. Generated by
    API Evangelist from Balad's published webhook documentation (StatusUpdateV2, Version 2 payload).
  contact:
    name: Balad Support
    email: support@balad.me
    url: https://developers.balad.tech/webhooks.md
  x-provenance:
    generated: '2026-07-18'
    method: generated
    source: https://developers.balad.tech/link-transaction-statusupdatev2-1733482m0.md
servers:
  partner-endpoint:
    host: partner-supplied.example
    protocol: https
    description: Partner-hosted HTTPS endpoint; must be whitelisted by Balad Ops before production delivery.
channels:
  transactionStatusUpdate:
    address: '{partnerWebhookUrl}'
    title: Link.Transaction.StatusUpdateV2
    description: Receive a notification whenever a transaction changes status.
    messages:
      statusUpdateV2:
        $ref: '#/components/messages/StatusUpdateV2'
operations:
  receiveStatusUpdate:
    action: receive
    channel:
      $ref: '#/channels/transactionStatusUpdate'
    summary: Transaction status update (event_type 994019)
    bindings:
      http:
        method: POST
    messages:
      - $ref: '#/channels/transactionStatusUpdate/messages/statusUpdateV2'
components:
  messages:
    StatusUpdateV2:
      name: Link.Transaction.StatusUpdateV2
      title: Transaction Status Update (V2)
      contentType: application/json
      headers:
        type: object
        properties:
          X-HMAC-SIGNATURE:
            type: string
            description: HMAC-SHA256 of the minified JSON payload, keyed with the 32-char Webhook Secret.
          User-Agent:
            type: string
            const: Balad Egypt
      payload:
        $ref: '#/components/schemas/EventEnvelopeV2'
  schemas:
    EventEnvelopeV2:
      type: object
      required: [id, eventType, timestamp, version, data]
      properties:
        id: {type: string, description: Unique identifier for this webhook event}
        eventType: {type: string, description: Event type; 994019 for transaction status updates}
        timestamp: {type: string, description: 'Event generation time, e.g. 25-Nov-2025 08:52:02 AM'}
        version: {type: string, const: '2'}
        data:
          type: object
          required: [referenceNumber, transactionStatusCode]
          properties:
            referenceNumber: {type: string, description: Your unique reference number for the transaction}
            transactionStatusCode: {type: integer, description: Numeric status code (see Get Transaction Status V2)}
            transactionStatusDescription: {type: string}
            reason: {type: string, description: Optional brief technical/internal reason for the change}
            failureDetails:
              type: [object, 'null']
              description: Present only when the status indicates a failure/rejection.
              properties:
                category: {type: string, example: COMPLIANCE_RESTRICTION}
                code: {type: string, example: CMP_001}
                message: {type: string}
                additionalInfo: {type: string}