Add webhook URL option to API calls

[john-zaprite]

Do webhook events get fired for all incoming payments?
If so, this is a privacy issue when connecting to third-party applications. Users likely don't want all incoming payment events sent out to a third-party.
A solution would be to allow applications to add a callbackUrl in each individual API call. For example:

$ curl -X POST http://localhost:9740/createinvoice \
    -u :phoenixd_api_password \
    -d description='my first invoice' \
    -d amountSat=100 \
    -d callbackUrl='https://app.zaprite.com/…' \
    -d externalId=foobar

This way, an application can POST API requests and receive only the relevant event callback. Users would not have to add Webhooks directly in phoenixd.

[pm47]

Do webhook events get fired for all incoming payments?

Yes

If so, this is a privacy issue when connecting to third-party applications.
an application can POST API requests and receive only the relevant event callback.

I can see how receiving only a specific event could be handy in some cases, but I don't get the privacy argument. Curious what kind of third party you would send your events to? Those are meant to be sent to a server you control and sending any events to a third party is a privacy issue?

There would have to be a default webhook though, because some events are not tied to a particular request. For example payments to a BOLT12 offer, on-chain payments, if/when we support it, or any generic event such as balance update etc.

[john-zaprite]

but I don't get the privacy argument.
Curious what kind of third party you would send your events to?

For our specific use-case, we would allow users to connect their node and accept incoming payments from Zaprite Checkouts. We need to know when the payments have been settled, and if we get the user to add a webhook then we'll know about every incoming payment to their node. That's a privacy issue.

There would have to be a default webhook though, because some events are not tied to a particular request

Yes exactly. I'd see this API webhook as a separate optional feature. Instead of users adding a Zaprite endpoint to their general phoenixd webhooks, we would just include our own in each payment we initiate. That way we only know about the payments originating on our platform.

[pm47]

Gotcha, will look into it.

I'm wondering: how does the invoice creation work? I suppose it has to be initiated by Zaprite Checkouts right, when a potential customer visits a checkout page? But the invoice is created in phoenixd?

[john-zaprite]

Yep. Zaprite just pings a node and requests an invoice to be created. We display it on our Checkouts and then either poll it for payment status and/or wait for a webhook.

[pm47]

Done in #85, released in 0.3.2.

[john-zaprite]

Amazing, thank you!