Webhooks
Together with the integration of the payment functionalities, MoneyHash recommends you set up a notification system to track all operations related to your business. This way, you can stay up to date with all operations related to each transaction. You can accomplish this using Webhooks or Redirects. This page focuses on the Webhooks solution.
What are Webhooks
Webhooks are HTTP POST requests that MoneyHash sends automatically to your server whenever an event occurs in the payment lifecycle. Instead of your system constantly polling for updates, MoneyHash pushes the information to you the moment something changes, keeping your backend in sync without any extra effort on your end.
MoneyHash webhooks will alert you when there is an update to any step of the payment cycle. There are webhooks for intents, transactions, card tokenizations, customers, subscriptions, payouts, and bulk payouts.
Let's say you want to know when a payment is complete so you can fulfill an order. When the intent reaches its final state, MoneyHash sends an intent.processed POST request to your webhook endpoint containing the intent ID and the final payment_status. With this information, you can complete any necessary backend action for your business, such as calling your shipping provider's APIs to schedule a shipment.
What Triggers a Webhook
A webhook fires whenever an operation changes status. This means a single payment can generate multiple webhook events. For example, a card payment going through 3DS authentication will fire a transaction.purchase.pending_authentication event when authentication starts, and then a transaction.purchase.successful event once it completes. Each event carries the full intent and transaction context so you always have the complete picture of what happened.
Best Practices
Your server should always return a 2xx response as soon as the webhook is received, before doing any processing. This tells MoneyHash the event was delivered successfully and prevents unnecessary retries. The actual business logic such as updating your database or triggering downstream actions should happen asynchronously after you have acknowledged receipt.
Do not reject a webhook because a certain parameter is missing or unexpected. MoneyHash may introduce new fields or event types over time, and a strict validation that rejects unknown fields can cause your integration to break unexpectedly.
Your webhook handler should be idempotent. MoneyHash retries webhook delivery until your server successfully acknowledges the event, so your endpoint may receive the same webhook more than once. Store a unique identifier from the webhook payload and skip any event you have already processed to avoid duplicate actions such as duplicate fulfillments, notifications, or ledger entries.
Webhook Security
While webhooks are a great way to communicate and receive updates, it is essential for security purposes to validate the event source and verify that the events were sent by MoneyHash. MoneyHash signs all webhook events sent to your endpoints with a signature that appears in each event's MoneyHash-Signature header. It allows you to verify that the events were sent by MoneyHash rather than a third party. Find out how to take full advantage of this at the Webhooks Signature page.
Webhook Retries
MoneyHash will retry sending you the webhook event gradually in case of failures. The retries approach ensures your server receives the transactions' updates. If the POST request fails, MoneyHash will perform a new POST request, increasing the waiting time as described below:
-
Retries sending event after 5 minutes.
-
Retries sending event after 30 minutes.
-
Retries sending event after 2 hours.
-
Retries sending event after 8 hours.
-
Retries sending event after 12 hours.
-
Retries sending event after 24 hours.
Further Webhooks
To learn more about the Webhooks on MoneyHash, you can explore the following content:
A step-by-step guide on testing and analyzing the webhooks related to a payment process.
A reference guide for all webhook events fired during payout intent and bulk payout request lifecycles.
All existing webhook types on MoneyHash and describe the information provided by each one.
How to validate the authenticity of the webhooks information to ensure MoneyHash provides the requests you are receiving.
Updated 26 days ago