📢 Webhooks

Webhooks let you receive real-time event notifications directly from the AUDD Mint platform. Instead of repeatedly polling APIs for updates, your systems can be automatically alerted whenever something changes. This makes it easy to keep your records up to date and trigger workflows the moment events occur.

Most events within the Mint environment can be connected to webhooks. Common use cases include tracking incoming deposits, monitoring withdrawals, following the outcome of mints and burns, and keeping tabs on Virtual Account (VA) updates. These will be explored further in examples below.

🛠️ Setting Up Webhooks for the First Time

Before you start integrating webhooks, there are a few key requirements. You’ll need a valid authorization token that will be included in every request so you can verify that events are really coming from AUDD Mint. Your system must also expose a public HTTPS endpoint that can accept POST requests. This endpoint should be designed with event-handling logic to capture and store events as they come in.

It’s also important that your endpoint is idempotent - in other words, if the same event is sent more than once, your system should process it only once. This protects against duplicate entries during retries.

When you’re ready to enable webhooks, simply provide the AUDD development team with three things:

1. Webhook Endpoint URL (publicly accessible HTTPS URL)
2. Webhook API Token (used to verify requests)
3. Subscribed Event Types (i.e: DEPOSIT for incoming deposits, WITHDRAWAL for outgoing withdrawals, MINT and BURN for the token leg of a trade, or BANK_ACCOUNT_UPDATE for updates to a VA)

📝 Registering your Webhook

To get your webhook live, you’ll need to share the following details with the AUDD team:

1. The Webhook URL where events should be sent.
2. The event types you want to subscribe to.
3. The authorization token used to verify requests.

Once these are provided, our AUDD team will configure the webhook settings on your behalf.

📦 Example Webhook Event Payloads

Here are a few sample payloads to illustrate what webhook events look like when they arrive. Every payload carries a transType you can route on.

💰 Deposit Event

{
    "transactionId": "123456",
    "bankTransactionId": "ref123",
    "transType": "DEPOSIT",
    "transStatus": "DONE",
    "company": {
        "id": "7890",
        "name": "CompanyName",
        "bankAccount": {
            "id": "4567",
            "nickname": "Account Name",
            "bsb": "123456",
            "accountNo": "987654321"
        }
    },
    "sourceBankAccount": {
        "bsb": "654321",
        "accountNo": "123456789",
        "accountHolderName": "Remitter Name"
    },
    "amount": 1000.00,
    "paymentRail": "Osko",
    "reference": "Payment for services",
    "description": "Invoice #123",
    "timestamp": "2024-08-05T10:00:00Z",
    "tradeId": null
}

Two additional fields appear on deposits depending on the status: failureReason when transStatus is FAILED, and refundReason when transStatus is REFUNDING or REFUNDED.

tradeId is populated when the deposit is the AUD settlement of a burn (the description then reads Sell ref XXXXXX). It matches the tradeId on the corresponding BURN event, so match on it rather than on the description.

🏦 Withdrawal Event

{
    "transactionId": "654321",
    "bankTransactionId": "ref654",
    "transType": "WITHDRAWAL",
    "transStatus": "DONE",
    "company": {
        "id": "7890",
        "name": "CompanyName",
        "bankAccount": {
            "id": "4567",
            "nickname": "Account Name",
            "bsb": "654321",
            "accountNo": "123456789"
        }
    },
    "destinationBankAccount": {
        "bsb": "123456",
        "accountNo": "987654321"
    },
    "amount": 500.00,
    "reference": "Refund",
    "description": "Order #456",
    "timestamp": "2024-08-05T10:05:00Z",
    "tradeId": null
}

tradeId is populated when the withdrawal is the AUD leg of a mint, and matches the tradeId on the corresponding MINT event.

🪙 Mint Event

Sent when the AUDD requested with POST /trades/buy reaches a final state on the blockchain. transStatus is DONE, FAILED or CANCELED; nothing is sent while the trade is pending.

{
    "transType": "MINT",
    "transStatus": "DONE",
    "tradeId": "trade_123456",
    "transactionId": "tx_123456",
    "blockchainTxHash": "0x9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b",
    "company": {
        "id": "7890",
        "name": "CompanyName",
        "bankAccount": {
            "id": "4567",
            "nickname": "Account Name"
        }
    },
    "asset": {
        "id": "asset_123456",
        "code": "AUDD",
        "issuer": "0xIssuerAddress"
    },
    "assetAmount": "1000.0000000",
    "fiat": {
        "currency": "AUD",
        "rate": "1.00"
    },
    "wallet": {
        "address": "0xCustomerWalletAddress",
        "id": null
    },
    "reference": "ref123",
    "memo": null,
    "timestamp": "2024-08-05T10:10:00.123Z"
}

🔥 Burn Event

Sent when the AUDD burned via POST /trades/sell reaches a final state on the blockchain. Same statuses as MINT. A DONE burn means the tokens were burned; the AUD proceeds are credited separately and confirmed by a DEPOSIT event with the same tradeId.

{
    "transType": "BURN",
    "transStatus": "DONE",
    "tradeId": "trade_654321",
    "transactionId": "tx_654321",
    "blockchainTxHash": "0x1f2e3d4c5b6a79880706050403020100ffeeddccbbaa99887766554433221100",
    "company": {
        "id": "7890",
        "name": "CompanyName",
        "bankAccount": {
            "id": "4567",
            "nickname": "Account Name"
        }
    },
    "asset": {
        "id": "asset_123456",
        "code": "AUDD",
        "issuer": "0xIssuerAddress"
    },
    "assetAmount": "500.0000000",
    "fiat": {
        "currency": "AUD",
        "rate": "1.00"
    },
    "wallet": {
        "address": null,
        "id": "wallet_654321"
    },
    "reference": "ref654",
    "memo": null,
    "timestamp": "2024-08-05T10:15:00.456Z"
}

Field notes for MINT and BURN:

• tradeId is the trade returned by POST /trades/buy or POST /trades/sell. Use it to correlate the event with your records and with the WITHDRAWAL (mint) or DEPOSIT (burn) event for the same trade.
• transactionId is the transaction on which the outcome was observed. For a trade split into several on-chain transactions it can differ from the id returned by POST /trades/*, so correlate on tradeId.
• blockchainTxHash can be null. On a failed BURN it echoes the blockchainTxId you submitted.
• company.bankAccount is the Virtual Account that funded the mint or receives the burn proceeds.
• assetAmount is a decimal string, not a number, so precision is preserved.
• wallet: on MINT, address is the wallet that received the AUDD and id is null. On BURN, id is the registered external wallet that sent the AUDD (the walletId you passed) and address is null.
• Treat tradeId + transStatus as your idempotency key for these events.

📝 VA Update Event

{
    "transType": "BANK_ACCOUNT_UPDATE",
    "id": "acc_12345",
    "status": "ACTIVE",
    "accountNo": "987654321",
    "bsb": "123-456",
    "reference": "Updated Account",
    "info": "Linked successfully",
    "virtualIban": "DE89 3704 0044 0532 0130 00",
    "providerType": "<redacted>"
}

✅ Verifying the Authorization Token

Every webhook request includes your authorization token in the header, either as Authorization or X-API-KEY. For example:

Authorization: Secret YOUR_WEBHOOK_TOKEN or X-API-KEY: YOUR_WEBHOOK_TOKEN

Your server must check this token before processing the payload. This verification step ensures that events are truly from the AUDD Mint and haven’t been spoofed.

📬 Responding to Webhook Events

When your system successfully processes a webhook, return an HTTP 2xx response such as 200 OK. This signals to the AUDD Mint that the event was received and handled correctly. Any other status code is recorded against the event as your response and is not retried automatically, so treat a non-2xx as something to reconcile on your side rather than as a request for redelivery.

🔁 Error Handling and Retries

If your endpoint cannot be reached, or does not answer within 60 seconds, the delivery is considered failed and AUDD Mint retries it, roughly every 90 seconds, up to 10 times. After that the event is held for investigation and the AUDD team is alerted. The same event can therefore arrive more than once when an earlier attempt timed out after you had already received it.