Overview

Webhooks allow you to receive real-time HTTP notifications of events relating to hosted customer onboarding, transactions, or deposits initiated through your API Keys.

It is essential to subscribe to the relevant webhooks, as it is Noah's method to notify you of updates, for which you may need to action processes within your application to, for example, credit or debit the accounts involved in a given transaction.

Customer Events are triggered when the customer has completed the hosted onboarding flow and submitted the form at the end of the process, as well as when the customer's hosted onboarding status changes. For details, see Customer.
Fiat Deposit Events are triggered on the event that a customer performs a Fiat Deposit to an assigned bank account number. For details, see FiatDeposit.
Transaction Events are triggered on the event that a transaction is created or the status of a transaction changes. For details, see Transaction.

Create a Webhook Subscription

1. Navigate to Configuration

Log in to the dashboard with your Noah Business Account and navigate to the API Configuration page, then click on the Webhooks tab. Here you can create a new webhook subscription via the User Interface by providing your subscription URL.

2. Configure Webhook Subscriptions

You will be prompted to enter the following details for each webhook subscription:

URL: This is the endpoint where you want to receive webhook notifications.
EventTypes: A list of event types you can subscribe to. Noah supports the 'Customer', 'FiatDeposit', and 'Transaction' event types.

3. Confirm Webhook Subscription Receipt

Your system will receive webhook notifications at the specified subscription URL for every hosted customer onboarding, transaction, or fiat deposit update. These notifications contain detailed information about the event, allowing your system to respond appropriately and in real-time.

Ensure that it's functioning correctly by triggering an event in the system. The webhook includes the version and occurrence time of the event to allow you to process the latest version of the event.

4. Secure Your Endpoint

Noah cryptographically signs all webhook requests sent to your endpoint. You should verify these signatures to confirm that the webhook genuinely originated from Noah and has not been tampered with.

How it works:

Noah signs the request body using our private key (ECDSA with SHA-384)
The signature is included in the Webhook-Signature header (base64-encoded)
You verify the signature using Noah's public key (provided below)

note

The public keys below are Noah's public keys for you to use when verifying webhooks. You do not need to generate or provide any keys to Noah — we handle the signing, you handle the verification.

Noah's Webhook Public Keys

Sandbox:

Production:

Node.js Verification Example

const crypto = require('crypto');

const NOAH_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEm8yBiD+kmVJ1Xc9sfRkDx0yo9+u8yiAD
PngI20KoEswz0gflp8o/z66Abqz/m9A1CBecixWdeT72pA8NZBJI6L6Osd8RV+yx
QArxeGKEVX/2QNrfPqeAKODHT5LdStGT
-----END PUBLIC KEY-----`;

function verifyWebhookSignature(requestBody, signatureHeader) {
  const signature = Buffer.from(signatureHeader, 'base64');
  const verifier = crypto.createVerify('SHA384');
  verifier.update(requestBody);
  return verifier.verify(NOAH_PUBLIC_KEY, signature);
}

Python Verification Example

import base64
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.serialization import load_pem_public_key
from cryptography.exceptions import InvalidSignature

NOAH_PUBLIC_KEY = b"""-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEm8yBiD+kmVJ1Xc9sfRkDx0yo9+u8yiAD
PngI20KoEswz0gflp8o/z66Abqz/m9A1CBecixWdeT72pA8NZBJI6L6Osd8RV+yx
QArxeGKEVX/2QNrfPqeAKODHT5LdStGT
-----END PUBLIC KEY-----"""

def verify_webhook_signature(request_body: bytes, signature_header: str) -> bool:
    try:
        signature = base64.b64decode(signature_header)
        public_key = load_pem_public_key(NOAH_PUBLIC_KEY)
        public_key.verify(signature, request_body, ec.ECDSA(hashes.SHA384()))
        return True
    except InvalidSignature:
        return False

Go Verification Example

import (
	"crypto/ecdsa"
	"crypto/sha512"
	"crypto/x509"
	"encoding/base64"
	"encoding/pem"
)

const noahPublicKeyPEM = `-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEm8yBiD+kmVJ1Xc9sfRkDx0yo9+u8yiAD
PngI20KoEswz0gflp8o/z66Abqz/m9A1CBecixWdeT72pA8NZBJI6L6Osd8RV+yx
QArxeGKEVX/2QNrfPqeAKODHT5LdStGT
-----END PUBLIC KEY-----`

func verifyWebhookSignature(body []byte, signatureHeader string) bool {
	signature, err := base64.StdEncoding.DecodeString(signatureHeader)
	if err != nil {
		return false
	}
	block, _ := pem.Decode([]byte(noahPublicKeyPEM))
	pub, err := x509.ParsePKIXPublicKey(block.Bytes)
	if err != nil {
		return false
	}
	ecdsaPub, ok := pub.(*ecdsa.PublicKey)
	if !ok {
		return false
	}
	hash := sha512.Sum384(body)
	return ecdsa.VerifyASN1(ecdsaPub, hash[:], signature)
}

Java Verification Example

import java.security.KeyFactory;
import java.security.PublicKey;
import java.security.Signature;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

public class WebhookVerifier {
    private static final String NOAH_PUBLIC_KEY = 
        "MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEm8yBiD+kmVJ1Xc9sfRkDx0yo9+u8yiAD" +
        "PngI20KoEswz0gflp8o/z66Abqz/m9A1CBecixWdeT72pA8NZBJI6L6Osd8RV+yx" +
        "QArxeGKEVX/2QNrfPqeAKODHT5LdStGT";

    public static boolean verifyWebhookSignature(byte[] requestBody, String signatureHeader) {
        try {
            byte[] signatureBytes = Base64.getDecoder().decode(signatureHeader);
            byte[] publicKeyBytes = Base64.getDecoder().decode(NOAH_PUBLIC_KEY);
            
            X509EncodedKeySpec keySpec = new X509EncodedKeySpec(publicKeyBytes);
            KeyFactory keyFactory = KeyFactory.getInstance("EC");
            PublicKey publicKey = keyFactory.generatePublic(keySpec);
            
            Signature signature = Signature.getInstance("SHA384withECDSA");
            signature.initVerify(publicKey);
            signature.update(requestBody);
            
            return signature.verify(signatureBytes);
        } catch (Exception e) {
            return false;
        }
    }
}

5. Webhook Acknowledgment and Retries

Acknowledgment Required: Ensure your endpoint responds with a 200 status to acknowledge the receipt of webhook notifications.
Retry Mechanism: If a notification fails to deliver, Noah will retry up to 7 times with increasing intervals between each attempt. The parameters for this are defined as:
- Interval: 12 seconds
- Max Retries: 7
- Exponential backoff: 5

Understanding Webhook Behavior

Why Multiple Webhooks?

A single user action (such as a fiat deposit) triggers multiple webhooks as it progresses through the system. Each webhook represents a status transition, not a duplicate notification. For example, a successful Bank OnRamp flow (fiat deposit → crypto payout) could generate multiple webhook events.

Status Values

All webhooks use these status values:

Status	Meaning
`Pending`	Processing in progress
`Settled`	Successfully completed
`Failed`	Did not complete; check for refund information

Transitions: Pending → Settled OR Pending → Failed

Handling Webhook Order

Webhook delivery order is not guaranteed. Your system must handle out-of-order events.

Use these fields to determine the latest state:

EventVersion — Timestamp-based version number (higher = newer)
Occurred — When the event happened

Recommended approach: Store EventVersion per resource ID. Only process webhooks where incoming EventVersion is more recent than stored EventVersion.

Important Notes

Ensure your endpoint is secured and can handle incoming HTTP requests.
Always test your webhook to confirm it's receiving and handling data as expected.
Monitor your endpoint for uptime and reliability.
The delivery order of webhook notifications is not guaranteed. Ensure your system can handle out-of-order events appropriately to maintain data consistency.

Whitelisting

Your service may require IP Address whitelisting to receive webhook notifications, if so, whitelist the following Noah IP addresses - which apply to both the Sandbox and Production environments.

35.178.216.8
3.10.163.222

Create a Webhook Subscription​

1. Navigate to Configuration​

2. Configure Webhook Subscriptions​

3. Confirm Webhook Subscription Receipt​

4. Secure Your Endpoint​

5. Webhook Acknowledgment and Retries​

Understanding Webhook Behavior​

Why Multiple Webhooks?​

Status Values​

Handling Webhook Order​

Important Notes​

Whitelisting​