mirror of
https://codeberg.org/wownero/wownero-lws
synced 2026-01-09 15:15:15 -08:00
Webhooks for New Accounts (#79)
This commit is contained in:
Lee *!* Clagett
committed by
Lee *!* Clagett
Lee *!* Clagett
parent
524e26e1a4
commit
aa171b77c3
@@ -144,14 +144,21 @@ This tells the scanner to rescan specific account(s) from the specified
|
||||
height.
|
||||
|
||||
### webhook_add
|
||||
This is used to track a specific payment ID to an address or all general
|
||||
payments to an address (where payment ID is zero). Using this endpint requires
|
||||
a web address or `zmq` for callback purposes, a primary (not integrated!)
|
||||
address, and finally the type ("tx-confirmation"). The event will remain in the
|
||||
database until one of the delete commands ([webhook_delete_uuid](#webhook_delete_uuid)
|
||||
or [webhook_delete](#webhook_delete)) is used to remove it. All webhooks are
|
||||
published over the ZMQ socket specified by `--zmq-pub` (when enabled/specified
|
||||
on command line) in addition to any HTTP server specified in the callback.
|
||||
This is used to track events happening in the database: (1) a new payment to
|
||||
an optional payment_id, or (2) a new account creation. This endpoint always
|
||||
requires a URL for callback purposes.
|
||||
|
||||
When the event type is `tx-confirmation`, this endpint requires a web address
|
||||
for callback purposes, a primary (not integrated!) address, and finally the
|
||||
type ("tx-confirmation"). The event will remain in the database until one of
|
||||
the delete commands ([webhook_delete_uuid](#webhook_delete_uuid) or
|
||||
[webhook_delete](#webhook_delete)) is used to remove it.
|
||||
|
||||
When the event type is `new-account`, this endpoint requires a web address
|
||||
for callback purposes, and the type ("new-account"). Spurious information
|
||||
will be returned for this endpoint to simplify the server implementation (i.e.
|
||||
several fields returned in the initial call are not useful to new account
|
||||
creations).
|
||||
|
||||
> The provided URL will use SSL/TLS if `https://` is prefixed in the URL and
|
||||
will use plaintext if `http://` is prefixed in the URL. If `zmq` is provided
|
||||
@@ -169,7 +176,8 @@ should be used, and (3) if the callback server is using "Let's Encrypt"
|
||||
used.
|
||||
|
||||
|
||||
#### Initial Request to server
|
||||
#### `tx-confirmation`
|
||||
##### Initial Request to server
|
||||
Example where admin authentication is required (`--disable-admin-auth` NOT
|
||||
set on start which is the default):
|
||||
```json
|
||||
@@ -222,7 +230,7 @@ executable, the event should be listed in the
|
||||
event will remain in the database until an explicit
|
||||
[`webhook_delete_uuid`](#webhook_delete_uuid) is invoked.
|
||||
|
||||
#### Callback from Server
|
||||
##### Callback from Server
|
||||
When the event "fires" due to a transaction, the provided URL is invoked
|
||||
with a JSON payload that looks like the below:
|
||||
|
||||
@@ -258,6 +266,71 @@ contain an entry in the `webhook_events_by_account_id,type,block_id,tx_hash,outp
|
||||
field of the JSON object provided by the `debug_database` command. The
|
||||
entry will be removed when the number of confirmations has been reached.
|
||||
|
||||
#### `new-account`
|
||||
##### Initial Request to server
|
||||
Example where admin authentication is required (`--disable-admin-auth` NOT
|
||||
set on start which is the default):
|
||||
```json
|
||||
{
|
||||
"auth": "f50922f5fcd186eaa4bd7070b8072b66fea4fd736f06bd82df702e2314187d09",
|
||||
"params": {
|
||||
"type": "new-account",
|
||||
"url": "http://127.0.0.1:7001",
|
||||
"token": "1234"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Example where admin authentication is not required (`--disable-admin-auth` set on start):
|
||||
```json
|
||||
{
|
||||
"params": {
|
||||
"type": "new-account",
|
||||
"url": "http://127.0.0.1:7001",
|
||||
"token": "1234"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
As noted above - `token` is optional - it will default to the empty string.
|
||||
|
||||
##### Initial Response from Server
|
||||
The server will replay all values back to the user for confirmation. An
|
||||
additional field - `event_id` - is also returned which contains a globally
|
||||
unique value (internally this is a 128-bit `UUID`). The fields
|
||||
`confirmations`, and `payment_id` are sent to simplify the backend, and
|
||||
can be ignored when the type is `new-account`.
|
||||
|
||||
Example response:
|
||||
```json
|
||||
{
|
||||
"payment_id": "0000000000000000",
|
||||
"event_id": "c5a735e71b1e4f0a8bfaeff661d0b38a"",
|
||||
"token": "1234",
|
||||
"confirmations": 1,
|
||||
"url": "http://127.0.0.1:7000"
|
||||
}
|
||||
```
|
||||
|
||||
If you use the `debug_database` command provided by the `monero-lws-admin`
|
||||
executable, the event should be listed in the
|
||||
`webhooks_by_account_id,payment_id` field of the returned JSON object. The
|
||||
event will remain in the database until an explicit
|
||||
[`webhook_delete_uuid`](#webhook_delete_uuid) is invoked.
|
||||
|
||||
##### Callback from Server
|
||||
When the event "fires" due to a new account creation, the provided URL is
|
||||
invoked with a JSON payload that looks like the below:
|
||||
|
||||
```json
|
||||
{
|
||||
"event_id": "c5a735e71b1e4f0a8bfaeff661d0b38a",
|
||||
"token": "",
|
||||
"address": "9zGwnfWRMTF9nFVW9DNKp46aJ43CRtQBWNFvPqFVSN3RUKHuc37u2RDi2GXGp1wRdSRo5juS828FqgyxkumDaE4s9qyyi9B"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### webhook_delete
|
||||
Deletes all webhooks associated with a specific Monero primary address.
|
||||
|
||||
|
||||
52
docs/zmq.md
52
docs/zmq.md
@@ -2,24 +2,28 @@
|
||||
Monero-lws uses ZeroMQ-RPC to retrieve information from a Monero daemon,
|
||||
ZeroMQ-SUB to get immediate notifications of blocks and transactions from a
|
||||
Monero daemon, and ZeroMQ-PUB to notify external applications of payment_id
|
||||
(web)hooks.
|
||||
and new account (web)hooks.
|
||||
|
||||
## External "pub" socket
|
||||
The bind location of the ZMQ-PUB socket is specified with the `--zmq-pub`
|
||||
option. Users are still required to "subscribe" to topics:
|
||||
* `json-full-pyment_hook`: A JSON array of webhook payment events that have
|
||||
recently triggered (identical output as webhook).
|
||||
* `msgpack-full-payment_hook`: A msgpack array of webhook payment events that
|
||||
have recently triggered (identical output as webhook).
|
||||
* `json-full-payment_hook`: A JSON object of a single webhook payment event
|
||||
that has recently triggered (identical output as webhook).
|
||||
* `msgpack-full-payment_hook`: A msgpack object of a webhook payment events
|
||||
that have recently triggered (identical output as webhook).
|
||||
* `json-full-new_account_hook`: A JSON object of a single new account
|
||||
creation that has recently triggered (identical output as webhook).
|
||||
* `msgpack-full-new_account_hook`: A msgpack object of a single new account
|
||||
creation that has recently triggered (identical output as webhook).
|
||||
|
||||
|
||||
### `json-full-payment_hook`/`msgpack-full-payment_hook`
|
||||
These topics receive PUB messages when a webhook ([`webhook_add`](administration.md)),
|
||||
event is triggered. If the specified URL is `zmq`, then notifications are only
|
||||
done over the ZMQ-PUB socket, otherwise the notification is sent over ZMQ-PUB
|
||||
socket AND the specified URL. Invoking `webhook_add` with a `payment_id` of
|
||||
zeroes (the field is optional in `webhook_add), will match on all transactions
|
||||
that lack a `payment_id`.
|
||||
event is triggered for a payment (`tx-confirmation`). If the specified URL is
|
||||
`zmq`, then notifications are only done over the ZMQ-PUB socket, otherwise the
|
||||
notification is sent over ZMQ-PUB socket AND the specified URL. Invoking
|
||||
`webhook_add` with a `payment_id` of zeroes (the field is optional in
|
||||
`webhook_add`), will match on all transactions that lack a `payment_id`.
|
||||
|
||||
Example of the "raw" output from ZMQ-SUB side:
|
||||
|
||||
@@ -63,3 +67,31 @@ matching is done by string prefixes.
|
||||
|
||||
> The `block` and `id` fields in the above example are NOT present when
|
||||
`confirmations == 0`.
|
||||
|
||||
### `json-full-new_account_hook`/`msgpack-full-new_account_hook`
|
||||
These topics receive PUB messages when a webhook ([`webhook_add`](administration.md)),
|
||||
event is triggered for a new account (`new-account`). If the specified URL is
|
||||
`zmq`, then notifications are only done over the ZMQ-PUB socket, otherwise the
|
||||
notification is sent over ZMQ-PUB socket AND the specified URL. Invoking
|
||||
`webhook_add` with a `payment_id` of zeroes (the field is optional in
|
||||
`webhook_add`), will match on all transactions that lack a `payment_id`.
|
||||
|
||||
Example of the "raw" output from ZMQ-SUB side:
|
||||
|
||||
```json
|
||||
json-full-new_account_hook:{
|
||||
"index": 2,
|
||||
"event": {
|
||||
"event": "new-account",
|
||||
"event_id": "c5a735e71b1e4f0a8bfaeff661d0b38a",
|
||||
"token": "",
|
||||
"address": "9zGwnfWRMTF9nFVW9DNKp46aJ43CRtQBWNFvPqFVSN3RUKHuc37u2RDi2GXGp1wRdSRo5juS828FqgyxkumDaE4s9qyyi9B"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notice the `json-full-new_account_hook:` prefix - this is required for the ZMQ
|
||||
PUB/SUB subscription model. The subscriber requests data from a certain "topic"
|
||||
where matching is done by string prefixes.
|
||||
|
||||
> `index` is a counter used to detect dropped messages.
|
||||
|
||||
Reference in New Issue
Block a user