Skip to main content

Configuration

Overview​

Transaction Webhooks allow you to receive real-time HTTP notifications of events relating to 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 credit or debit the accounts involved in a given transaction.

  • Transaction Events are triggered on the event that a transaction is created or the status of a transaction changes.
  • Fiat Deposit Events are triggered on the event that a customer performs a Fiat Deposit to an assigned bank account number.

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. Currently, our system supports the 'Transaction' and 'FiatDeposit' event types.

3. Confirm Webhook Subscription Receipt​

Your system will receive webook notifications at the specified subscription URL for every 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 a transaction in the system or simulating a fiat deposit. The webhook includes the version and occurrance time of the event to allow you to process the latest version of the event.

4. Secure Your Endpoint​

Verify the webhook signature:

  • The signature is included in the Webhook-Signature header.
  • Request body is signed using ECDSA algorithm with SHA384.
  • Verify the signature with the key corresponding to the environment:

Sandbox webhook public key:

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

Production webhook public key:

-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAELKJhxcUGJr3XgRrf+laSAVHvp31wFhE2
XdicXvF0DAdKzSPN8bkSdjrsUA6nnVUq3M47Y7RUYugMfkagaYjUExQZVjpMFg0P
DnXWl9y0dXYDq+pzYhAgL+MNpnY0eJ78
-----END PUBLIC KEY-----

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 5 times with increasing intervals between each attempt. The parameters for this are defined as:
    • Interval: 5 seconds
    • Max Retries: 5
    • Exponential backoff: 3

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