Invoice Ready Webhook

4 min

Amberflo.io integrates with Stripe and AWS Marketplace to automatically handle invoice payments. However, you’re not limited to these providers. If you use a different payment system—or manage your own—you can configure a webhook to be notified when new invoices are ready for payment, enabling more streamlined and automated billing workflows.

Invoice Ready Webhook

An Invoice Ready Webhook is an HTTP POST request sent from Amberflo to an endpoint you control. Each time an invoice is ready to be paid, Amberflo emits a ready-product-invoices event.

To start receiving these notifications, you’ll need to subscribe to the event by setting up a webhook endpoint and registering it with Amberflo.

You can do so by making a POST request to the Webhook API . Here is an example:

curl --request POST \
     --url https://app.amberflo.io/webhook \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-api-key: <your-amberflo-api-key>' \
     --data '
{
     "authHeader": [
          "X-Auth",
          "g5DC1BDw5BjXDT0RrDhVDqLMuy39fQAI"
     ],
     "topic": "ready-product-invoices",
     "destinationUrl": "https://example.com/webhook-endpoint/"
}
'

Notice the authHeader parameter. This header will be added to the webhook request in order to allow your endpoint to authenticate it.

Now, whenever there is a new invoice ready to be paid, you'll get a POST request (like the one below) on your endpoint.

Sample Webhook Request

This is what a webhook request to your endpoint will look like:

POST https://example.com/webhook-endpoint/ content-type: application/json user-agent: Amberflo.io Webhook Service x-auth: g5DC1BDw5BjXDT0RrDhVDqLMuy39fQAI

{
    "topic": "ready-product-invoices",
    "eventTime": 1659711395409,
    "eventId": "1bf92cf0-1d99-11ed-90a2-4fb51c754f3b",
    "data": {
        "invoiceUri": "payments/invoices/account_id=3/customer_id=eda5be25-f145-4448-b85c-6dc6dce1a2ac/product_id=1/product_plan_id=2b08a8f9-f70e-40e2-b595-06b6483c5d91/year=2022/month=02/day=06",
        "invoiceKey": {
            "accountId": "3",
            "customerId": "eda5be25-f145-4448-b85c-6dc6dce1a2ac",
            "productId": "1",
            "productPlanId": "2b08a8f9-f70e-40e2-b595-06b6483c5d91",
            "year": 2022,
            "month": 2,
            "day": 6
        },
        "planBillingPeriod": { "interval": "month", "intervalsCount": 3 },
        "planName": "Starter Plan",
        "invoiceStartTimeInSeconds": 1644105600,
        "invoiceEndTimeInSeconds": 1651795200,
        "gracePeriodInHours": 24,
        "productItemInvoices": [
            {
                "key": {
                    "accountId": "3",
                    "customerId": "eda5be25-f145-4448-b85c-6dc6dce1a2ac",
                    "productId": "1",
                    "productPlanId": "2b08a8f9-f70e-40e2-b595-06b6483c5d91",
                    "year": 2022,
                    "month": 2,
                    "day": 6,
                    "productItemKey": "6c1b443e-8b0a-4182-a640-caeb598eb0a5"
                },
                "productItemId": "6c1b443e-8b0a-4182-a640-caeb598eb0a5",
                "productItemName": "postman calls",
                "meterApiName": "ApiCalls-From-Postman",
                "productPlanName": "Starter Plan",
                "productItemVariants": [
                    {
                        "key": "",
                        "itemDimensions": {},
                        "hourlyBillInfos": null,
                        "totalBill": {
                            "priceInCredits": null,
                            "priceInBaseCurrency": 41010309,
                            "startTimeInSeconds": 1644105600,
                            "endTimeInSeconds": 1651795200,
                            "meterUnits": 41010420,
                            "price": 41010309,
                            "meteredUnitsPerTier": { "0": 111, "1": 41010309 }
                        },
                        "lateArrivalMeters": 0
                    }
                ],
                "totalBill": {
                    "priceInCredits": null,
                    "priceInBaseCurrency": 41010309,
                    "startTimeInSeconds": 1644105600,
                    "endTimeInSeconds": null,
                    "meterUnits": 41010420,
                    "price": 41010309,
                    "meteredUnitsPerTier": null
                }
            }
        ],
        "appliedPromotions": [],
        "productPlanFees": [
            {
                "costInCredits": null,
                "costInBaseCurrency": 200,
                "id": "fee_2",
                "name": "Recurring Rate",
                "description": "recurring fee",
                "cost": 200,
                "isOneTimeFee": false,
                "isProrated": false,
                "prorateToDay": false,
                "discountable": false,
                "prepayable": false
            }
        ],
        "totalBill": {
            "itemPrice": 41010309,
            "fixPrice": 200,
            "prepaid": 0,
            "totalDiscount": 0,
            "totalPriceBeforeDiscount": 41010509,
            "totalPriceBeforePrepaid": 41010509,
            "discountableFixPrice": 0,
            "discountableBasePrice": 41010309,
            "prepaidableFixPrice": 0,
            "prepayableNotDiscountableFees": 0,
            "totalPrepayablePrice": 41010309,
            "startTimeInSeconds": 1644105600,
            "endTimeInSeconds": 1651795200,
            "totalPrice": 41010509
        },
        "invoicePriceStatus": "price_locked",
        "creditUnit": null,
        "paymentStatus": "pre_payment",
        "paymentCreatedInSeconds": null,
        "externalSystemStatus": null,
        "invoiceBillInBaseCurrency": {
            "itemPrice": 41010309,
            "fixPrice": 200,
            "prepaid": 0,
            "totalDiscount": 0,
            "totalPriceBeforeDiscount": 41010509,
            "totalPriceBeforePrepaid": 41010509,
            "discountableFixPrice": 0,
            "discountableBasePrice": 41010309,
            "prepaidableFixPrice": 0,
            "prepayableNotDiscountableFees": 0,
            "totalPrepayablePrice": 41010309,
            "startTimeInSeconds": 1644105600,
            "endTimeInSeconds": 1651795200,
            "totalPrice": 41010509
        },
        "invoiceBillInCredits": null,
        "availablePrepaidLeft": 0,
        "availablePrepaidLeftBaseCurrency": 0,
        "availablePrepaidLeftInCredits": null,
        "availablePayAsYouGoMoney": 0,
        "availablePayAsYouGoMoneyInBaseCurrency": 0,
        "availablePayAsYouGoMoneyInCredits": null,
        "paymentCurrencyInfo": null,
        "paymentMethod": null
    }
}

Note that the content of data is the same that is returned by the Customer Invoice API, so you can always call it to verify the invoice status.

Endpoint Requirements

Amberflo's webhook system requires your endpoint to return a 200 HTTP status code to indicate successful receipt of the webhook. Any other status code will be treated as a failure.

When a delivery fails, Amberflo will retry the request a few times. Because of this, your endpoint must be idempotent, meaning it should handle repeated identical requests without unintended effects. For invoice-related events, the invoiceUri can be used as an idempotency key to safely identify and process duplicates.

Since webhook delivery attempts are limited, it's important to implement a fallback mechanism to ensure invoices are properly handled even if a webhook fails. You can periodically poll the following APIs:

Customer Invoice API – to retrieve a list of all invoices for a specific customer.
Account Event API – to check whether there have been any failed webhook delivery attempts.