Invoicing
Invoice Ready Webhook
4 min
amberflo io integrates with payments stripe integration and aws marketplace integration 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