# Notifications {% hint style="info" %} Please note that only the events visible by the API Operator who registered the webhook configuration can be received as notifications. Administrators can enable "view-all" permission for an API Operator (via the Users section) for him to receive all webhook notifications. {% endhint %} ## Notifications The notification feature allows you to be notified when an API user receives an important event. To receive a webhook notification, you must first register your target endpoint via `PUT /notifications/configuration` Once done, your web server will be called via POST with a json payload such as this one: ``` {'payload_type': 'TRANSACTION', 'event_type': 'NEW_TRANSACTION_HAS_BEEN_RECEIVED', 'id': 10} ``` * `payload_type`: Enum identifying the type of the Vault object the notification is about. * `event_type`: Enum identifying uniquely the exact event that triggered the notification. Can be used to run specific actions for specific events. * `id`: Id of the Vault object. Together with `payload_type` they allow you to fetch the full object with the corresponding endpoint. {% hint style="info" %} We have a retry policy that uses exponential backoff with a starting interval of 5 seconds, doubling up to a maximum of 30 minutes, and retries are capped at 100 attempts. {% endhint %} Below is a list and short description of the event types API operators can receive: | Event Type | Payload Type | Description | | ---------------------------------------- | ------------ | ------------------------------------------------------- | | NEW\_TRANSACTION\_HAS\_BEEN\_SIGNED | TRANSACTION | A new transaction has been signed by the HSM | | NEW\_TRANSACTION\_HAS\_BEEN\_BROADCASTED | TRANSACTION | An new transaction has been broadcast | | NEW\_TRANSACTION\_HAS\_FAILED | TRANSACTION | A new transaction has failed upon broadcast | | NEW\_TRANSACTION\_HAS\_BEEN\_ABORTED | TRANSACTION | A new transaction has been aborted by a User | | NEW\_TRANSACTION\_HAS\_BEEN\_RECEIVED | TRANSACTION | A new transaction has been received | | NEW\_TRANSACTION\_HAS\_BEEN\_SCORED | TRANSACTION | A new transaction has been scored by a KYT provider | | REQUEST\_HAS\_BEEN\_CREATED | REQUEST | A new request has been created | | REQUEST\_HAS\_RECEIVED\_AN\_APPROVAL | REQUEST | A request has received an approval | | REQUEST\_HAS\_REACHED\_STEP | REQUEST | A request has reached a new approval step | | REQUEST\_HAS\_REACHED\_QUORUM | REQUEST | A request has reached the required quorum | | REQUEST\_HAS\_BEEN\_ABORTED | REQUEST | A request has been aborted | | REQUEST\_HAS\_EXPIRED | REQUEST | A request has been pending for too long and has expired | | NEW\_USER\_HAS\_BEEN\_CREATED | USER | A new user has been created | | USER\_HAS\_BEEN\_EDITED | USER | A user has been edited | | USER\_HAS\_BEEN\_REVOKED | USER | A user has been revoked | | USER\_HAS\_BEEN\_SUSPENDED | USER | A user has been suspended | | USER\_HAS\_BEEN\_UNSUSPENDED | USER | A user has been unsuspended | | NEW\_GROUP\_HAS\_BEEN\_CREATED | GROUP | A new group has been created | | GROUP\_HAS\_BEEN\_EDITED | GROUP | A group has been edited | | GROUP\_HAS\_BEEN\_REVOKED | GROUP | A group has been revoked | | NEW\_ACCOUNT\_HAS\_BEEN\_CREATED | X\_ACCOUNT | A new account has been created | | ACCOUNT\_HAS\_BEEN\_EDITED | X\_ACCOUNT | An account has been edited | | NEW\_ENTITY\_HAS\_BEEN\_CREATED | ENTITY | A new entity has been created | | ENTITY\_HAS\_BEEN\_EDITED | ENTITY | An entity has been edited | | ENTITY\_HAS\_BEEN\_REVOKED | ENTITY | An entity has been revoked | | NEW\_WHITELIST\_HAS\_BEEN\_CREATED | WHITELIST | A new whitelist has been created | | WHITELIST\_HAS\_BEEN\_EDITED | WHITELIST | A whitelist has been edited | Note: `X_ACCOUNT` can be one of BITCOIN\_ACCOUNT, ETHEREUM\_ACCOUNT, ERC20\_ACCOUNT, ... By design, we've reduced the number of information in the payload to the minimum as we can't guarantee the security of the channel the same way we do with the LAM. However, using the provided `id` you can query the LAM to get more information. You can also make sure the payload is genuine with the shared secret you've provided during registration. We send you the following HTTP Header `X-Ledger-Signature: t=,v1=` * `timestamp` is a unix epoch timestamp * `signature` is a hmac sha256 signature computed with your secret and the concatenation of the: * timestamp as a string * character "." * json payload Here is an example of signature validation and a request to the LAM using python / flask: ```python SECRET = "mysecret" USER = "api_lam_user" @app.route("/", methods=["POST"]) def webhook(): ledger_signature = request.headers["X-Ledger-Signature"] for elem in ledger_signature.split(","): k, v = elem.split("=") if k == "t": timestamp = v elif k == "v1": signature = v if time.time() - int(timestamp) > 5 * 60: raise ValueError("message is too old, possible replay attack") to_sign = timestamp.encode() + b"." + request.data computed_signature = hmac.new(SECRET.encode(), to_sign, "sha256").hexdigest() if not hmac.compare_digest(signature, computed_signature): raise ValueError("signature mismatch") if request.json.get("payload_type") == "TRANSACTION": tx_id = request.json["id"] tx = requests.get( f"http://vault-lam:5000/transactions/{tx_id}", headers={"X-Ledger-API-User": USER, "Content-Type": "application/json"}, ) print(tx.json()) # do something with the transaction ``` {% content-ref url="/spaces/eiMuD6iCzDmjXi49ybSt/pages/wyQEcf96c1xK4L8QhbGy" %} [Set Notification Configuration](/api-documentation/reference/api-reference/notifications/set-notification-configuration.md) {% endcontent-ref %} {% content-ref url="/spaces/eiMuD6iCzDmjXi49ybSt/pages/nHJbWC2PTDTVIijsOW0t" %} [Get Notification Configuration](/api-documentation/reference/api-reference/notifications/configuration.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.enterprise.ledger.com/api-documentation/reference/api-reference/notifications.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.