Invoicing
Invoice Ready Webhook
4min
amberflo io integrates with payments stripe integration and aws marketplace integration for automatically settling invoices, but you are not limited to these payment providers if you have your own payment system or use a different service, you can set up a webhook to be notified of new invoices that are ready to be paid and improve your payment automation invoice ready webhook a webhook is an http post request that we make to an endpoint you control, with some specific payload every time a new invoice is ready to be paid, amberflo publishes the ready product invoices event in order to receive the webhook request, you'll need to subscribe to it 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 expects the endpoint to return a status code 200 upon success any other status code will be considered a failure the webhook system will retry a few times to send the request whenever there is a failure for this reason, it is important that the endpoint be idempotent , as the same event may hit it multiple times for the case of invoices, you can use the invoiceuri as idempotence key because there is a limited number of attempts to send the webhook, your system should have a fallback mechanism to ensure the invoices get settled you can achieve this by periodically checking the customer invoice ap i and the account event api the first lets you list all invoices for a given customer, while the later lets you check if there have been failed attempts to send the webhook