Skip to main content
Asset uses webhooks to send notifications regarding specific requests and updates about the platform.

​
Configuring Webhooks

  • In the Asset Dashboard, go to Developers → Webhooks.
  • Enter your Endpoint URL (HTTPS only).
  • (Optional) Add custom Headers such as an Authorization token or an x-asset-signature secret.
  • Click Save.

​
Disabling Webhooks

There might be times in which you want to temporarily disable webhooks. To do this, follow the steps below:
  1. In the Asset Dashboard, open Developers → Webhooks.
  2. Toggle Enabled off.
  3. Click Save.

​
Retries

If there is non-200 response or the request times out, Asset will retry the request up to four more times, each with an exponential backoff. The first delay will be 10 seconds, and subsequent delays will double from there.

​
Headers

Every webhook request comes with two headers asset-id and asset-signature. The asset-id header uniquely identifies the webhook request, and asset-signature is the signature of the request. You can use the public key at https://api.getasset.com/.well-known/jwks.json to validate the signature. Below is a sample Python code snippet that shows how to validate the signature. 
import json
import base64
import requests
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import rsa, padding
from jwcrypto import jwk

def base64url_decode(val):
    val += "=" * (-len(val) % 4)  # Fix padding
    return base64.urlsafe_b64decode(val)

asset_id = "<VALUE FROM HEADER>"
asset_signature = "<VALUE FROM HEADER>"
body = <BODY OF WEBHOOK MESSAGE>
payload = f"{asset_id}.{json.dumps(body)}"
decoded_signature = base64url_decode(asset_signature)

# Download the public key for signature verification and convert to RSA format
resp = requests.get("https://api.getasset.com/.well-known/jwks.json").json()
key = jwk.JWK.from_json(json.dumps(resp["keys"][0]))
n = int.from_bytes(base64url_decode(key.get("n")), "big")
e = int.from_bytes(base64url_decode(key.get("e")), "big")
public_numbers = rsa.RSAPublicNumbers(e, n)
rsa_key = public_numbers.public_key(default_backend())

# Validate the signature
rsa_key.verify(
    decoded_signature,
    payload.encode(),
    padding.PKCS1v15(),
    hashes.SHA256(),
)

​
Notifications

​
Plaid connections

For bank integrations, we have the following notifications available:
  • PLAID_ACCOUNT_CONNECTED: Sent when a new account is connected via Plaid.
  • PLAID_ACCOUNT_DISCONNECTED: Sent when an existing account is disconnected through the Plaid link flow.
  • PLAID_ACCOUNT_EXPIRED: Sent when Plaid detects that the account connection is not active. This means the account must be reconnected.
  • PLAID_TRANSACTIONS_SYNCED: Sent when new transactions have been synced for a Plaid-connected account.
All notifications above have the same message structure: 
{
  "type": "<PLAID_ACCOUNT_CONNECTED, PLAID_ACCOUNT_DISCONNECTED, PLAID_ACCOUNT_EXPIRED, PLAID_TRANSACTIONS_SYNCED>",
  "content": {
    "business_id": "biz_Pk2fNFDd8wj7EFeLWJywc7",
    "timestamp": "<current timestamp in UTC>",
    "account_id": "<the plaid linked item id>"
  }
}

​
Bookkeeping requests

As the books are being completed for a business, Asset will send requests that lists the set of tasks that need to be completed by the business owner. Message structure: 
{
  "type": "TASK_REQUEST",
  "content": {
    "business_id": "biz_Pk2fNFDd8wj7EFeLWJywc7",
    "task_types": [
      "categorize_transaction",
      "reconnect_account",
      "request_other_document",
      "request_receipt",
      "request_statement",
      "review_personal_transaction",
      "other"
    ]
  }
}
In addition, when the business owner has completed the tasks, a notification is also sent. Message structure: 
{
  "type": "TASKS_REQUEST_COMPLETED",
  "content": {
    "business_id": "biz_Pk2fNFDd8wj7EFeLWJywc7",
    "timestamp": "<current timestamp in UTC ISO 8601>"
  }
}
Questions? Reach out via our Contact form or email support@getasset.com.

​
Business notifications

We have the following notifications when a Business changes state:
  • BUSINESS_CREATED: Sent when a business is created.
  • BUSINESS_ACTIVATED: Sent when an inactive business is activated.
  • BUSINESS_DEACTIVATED: Sent when an active business is deactivated.
Message structure: 
{
  "type": "BUSINESS_CREATED",
  "content": {
    "business_id": "biz_Pk2fNFDd8wj7EFeLWJywc7",
    "business_external_id": "<the external business id>",
    "timestamp": "<current timestamp in UTC ISO 8601>"
  }
}