📢 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, 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, 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:

💰 Deposit Event

{
    "transNo": "123456",
    "transRef": "ref123",
    "transType": "DEPOSIT",
    "transStatus": "SUCCESS",
    "company": {
        "id": "7890",
        "name": "CompanyName",
        "bankAccount": {
            "id": "4567",
            "nickname": "Account Name",
            "bsb": "123-456",
            "accountNo": "987654321"
        }
    },
    "sourceBankAccount": {
        "bsb": "654-321",
        "accountNo": "123456789",
        "name": "Remitter Name"
    },
    "amount": 1000.00,
    "reference": "Payment for services",
    "description": "Invoice #123",
    "timestamp": "2024-08-05T10:00:00Z"
}

🏦 Withdrawal Event

{
    "transNo": "654321",
    "transRef": "ref654",
    "transType": "WITHDRAWAL",
    "transStatus": "SUCCESS",
    "company": {
        "id": "7890",
        "name": "CompanyName",
        "bankAccount": {
            "id": "4567",
            "nickname": "Account Name",
            "bsb": "654-321",
            "accountNo": "123456789"
        }
    },
    "destinationBankAccount": {
        "bsb": "123-456",
        "accountNo": "987654321"
    },
    "amount": 500.00,
    "reference": "Refund",
    "description": "Order #456",
    "timestamp": "2024-08-05T10:05:00Z"
}

📝 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": "BANKING_CIRCLE"
}

📘

Understanding your Updates:

Check out our Status Codes guide for more information on reading your event updates.

✅ Verifying the Authorization Token

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

Authorization: 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. If your server returns any non-2xx response, it will be treated as a failure, and the event will be retried.

🔁 Error Handlings and Retries

The AUDD Mint is designed to retry failed webhook deliveries up to 10 times. Retries follow an exponential backoff strategy, meaning the time between attempts increases with each failure. This helps protect both your system and the Mint platform from being overloaded.

👍

Avoid Double-Ups:

To mitigate duplicate processing during retries, always ensure your webhook endpoint is idempotent. This way, even if the same event is delivered multiple times, it won’t be processed more than once.