Recommendations for folks who use webhooks

[vindard]

Description

We've had a recent API use-case request to be able to monitor the status of a generated invoice to see when it is paid (@john-magill shared this flow in #1239).

We currently have a graphql subscription for this that we use in the galoy-pay repo (see here), which requires being able to use websockets wherever the solution is being deployed.

There are some cases though where setting up a ws/wss connection is tricky, for example with serverless NextJS apps.

Are we aware of any potential solutions to this specific need?

[dolcalmi]

• as far as I remember we use WS as transport protocol for subscriptions, even if you check our test client use ws https://github.com/GaloyMoney/galoy/blob/main/test/helpers/apollo-client.ts#L55
• Not sure if I am understanding correctly but they dont need an api key.. or will we add/remove validation filters for that cases?
• Having a subscription (ws connection) for each invoice is not a good idea because they can have hundreds of clients.
• setting up a ws/wss connection is tricky, for example with serverless NextJS apps. -> serverless is not a correct approach if they plan to use persistent connections (like ws)

Solution probably webhooks would be a good solution for this case. The easiest way to implement it would be:

• User request an invoice (on behalf) with metadata (including a 'callback' field)
• When trigger has an update for the invoice we check if its metadata includes a callback and we post the response to that endpoint
• User receives the POST request (this can be a serverless implementation)
• With the hash, the user query the transaction status (we cant trust in a post request) and validate the final status

the advantage with this approach is that we can implement it in the same metadata PR and we only have to do a small change in trigger invoice handler (fire and forget POST without additional/external services and/or pods).

[john-zaprite]

We don't plan on ever having to use ws so we're trying to avoid that. Webhooks would definitely be the ideal solution here. Let me know if you need more info from me, or need me to test anything. Thanks!

[nicolasburtey]

discussed with @john-magill some days ago.

having a webhook per invoice on the current non auth api is not ideal. because an attacker could use it to call any url repeatedly (create a 1 sat invoice, pay it, our server will call the webhook, repeat).

I think one way to go would be to have an entity in the system call partner that would have some privilege.

one of them could be to have a webhook called (the one register for the partner) whenever an invoice the partner has generated is being paid.

another example of an API a partner could have is the idea of being able to having the partner being able to create an account on behalf of the end user. Mike from Oshi suggested this would be a great API for them to have: they meet a merchant, Oshi initializes a client account creation for the merchant (merchant receives an email that he needs to confirm). from here, Oshi can start creating invoice on behalf of the merchant. the merchant later complete his account creation process.

[nicolasburtey]

having a webhook per invoice on the current non auth api is not ideal. because an attacker could use it to call any url repeatedly (create a 1 sat invoice, pay it, our server will call the webhook, repeat).

one way to prevent this attack vector would be to have a list of allowlist for domains

[nicolasburtey]

also needed: non subscription api, for developers using serverless api that can't use subscriptions

[nicolasburtey]

we now have a webhooks. there are more work needed for some cases on the webhook side but I'll create another issue for it,