Webhooks¶

Webhooks are the best way to make your application responsive to new or changing data.

Webhooks are only available for full apps.

When you sign up for a full app you will be asked for your webhook url. Your webhook url must be a valid https uri that can accept POST requests. If you want to add or change your app's webhook url in the future, reach out to Akahu support.

Verifying a Webhook¶

Webhooks are signed by a private RSA key held by Akahu.

The signature can be found in the X-Akahu-Signature header (base 64 encoded).

The key ID of the signing key is sent in the X-Akahu-Signing-Key header.

Getting the Signing Key¶

In order to verify the signature, you must first retrieve the public key of the RSA keypair used to sign the webhook payload. This can be done by making a GET request to https://api.akahu.io/keys/{keyID}. The response payload will contain the public signing key in PEM format.

{
  "success": true,
  "item": "-----BEGIN RSA PUBLIC KEY-----\n..."
}

Caching¶

You may cache the signing key (preferably for 24 hours), however whenever the key ID changes, your application must fetch the new key from Akahu, and wipe previously cached keys. This is to ensure that if key rotation happens, your application will not continue to allow webhooks signed with an expired key.

Verification¶

Once you have the public signing key, compute the RSA-SHA256 signature of the webhook body and ensure it matches the X-Akahu-Signature header. An example using nodeJS is given below.

const crypto = require("crypto");

const verify = crypto.createVerify("sha256");
verify.update(request.body);
verify.end();
const isValid = verify.verify(
  public_signing_key,
  request.headers["x-akahu-signature"],
  "base64"
);

if (isValid) {
  console.log("This webhook is from Akahu!");
} else {
  console.log("Invalid webhook caller!");
}

What a Webhook Looks Like¶

Akahu has a hierarchical webhook type structure.

At a high level there is webhook_type which is the type of object that triggers the webhook (for example a USER, ACCOUNT orTRANSACTION). Within each webhook_type there are defined webhook_codes which are the type of event that triggered the webhook (eg. UPDATE, DELETE).

All webhooks have the following basic structure:

{
  "success": "<boolean>",
  "webhook_type": "<string>",
  "webhook_code": "<string>",
  "state": "<string>", // If supplied when creating the webhook
  "error": "<string>|<undefined>" // Present if success is false
}

The types of webhook supported by Akahu are defined below:

IDENTITY¶

Code	Description	Additional Fields
CREATE, UPDATE, DELETE	A user's identity information has changed. This could be the user's name, an email address, or any other identity information you have access to.	item_id The user ID.

ACCOUNT¶

Code	Description	Additional Fields
CREATE	A new account has been connected.	item_id The account ID.
UPDATE	An account has been updated. The fields that have changed are included in the payload so that recipients can determine if the update is relevant (e.g. an app to help with tax might not care about auto_payments).	item_id The account ID. updated_fields An array of strings.
DELETE	An account has been deleted.	item_id The account ID.

TRANSACTION¶

Code	Description	Additional Fields
INITIAL_UPDATE	Akahu has retrieved the initial transactions for an account. By default this is all transactions from the last 90 days.	item_id The account ID. new_transactions The number of new transactions. new_transaction_ids An array of transaction IDs.
DEFAULT_UPDATE	Akahu has retrieved new transactions.	item_id The account ID. new_transactions The number of new transactions. new_transaction_ids An array of transaction IDs.
DELETE	One or more transactions have been deleted.	item_id The account ID. removed_transactions An array of transaction IDs.

TRANSFER¶

Code	Description	Additional Fields
UPDATE	A transfer has changed its status.	item_id The transfer ID. status The new status. status_text A description of the status, if present.

PAYMENT¶

Code	Description	Additional Fields
UPDATE	A payment has changed its status.	item_id The payment ID. status The new status. status_text A description of the status, if present.