Overview

When to utilize Webhooks

Webhooks are essential for managing behind-the-scenes transactions. They allow you to receive alerts for asynchronous updates to transaction statuses. MoonPay can send webhook events that notify your application whenever an activity occurs on your account. This feature is particularly valuable for tracking changes like transaction status updates, that are not triggered by a direct API request.

These notifications are delivered through HTTP POST requests to any endpoint URLs you’ve specified in your account’s Webhooks settings. MoonPay is capable of sending a single event to multiple webhook endpoints.

Configuring your Webhook Settings

Webhooks are configured in your MoonPay dashboard’s Webhook settings. Click Add Endpoint to reveal a form where you can add a new URL for receiving webhooks.

You can enter any URL as the destination for events. However, this should be a dedicated page on your server that is set up to receive webhook notifications. You can choose to be notified of all event types, or only specific ones.

Using test or live API keys determines whether test events or live events are sent to your configured URL. If you want to send both live and test events to the same URL, you need to create two separate settings. You can add as many URLs as you like.

Delivery, retries and ordering

Every event is delivered as an HTTP POST request with a JSON body, signed with the Moonpay-Signature and Moonpay-Signature-V2 headers (see Request signing).

• Acknowledge quickly. Respond with a 2xx status code within 5 seconds. Any non-2xx response, timeout or connection error counts as a failed delivery attempt. If you need to do heavy processing, acknowledge first and process asynchronously.
• Failed deliveries are retried. MoonPay retries a failed delivery up to 9 times with exponential backoff, starting at 1 second and roughly doubling per attempt. Once retries are exhausted the event is not redelivered.
• Delivery is at-least-once. Duplicate deliveries can occur, so make your handler idempotent — for example, deduplicate on the event type plus the transaction id and updatedAt values in the payload.
• Events are not ordered. Events can arrive out of order, especially when retries are involved. Use the updatedAt timestamp inside the payload rather than arrival order to decide whether an event is newer than the state you have stored.

Receiving a Webhook Notification

Setting up an endpoint to receive webhook HTTP POST requests in the JSON request body can vary based on your backend stack and hosting environment. Below are some methods to achieve this using different technologies:

Python with Flask

Flask is a lightweight WSGI web application framework in Python.

from flask import Flask, request, jsonify

app = Flask(**name**)

@app.route('/webhook', methods=['POST'])
def webhook(): # Flask automatically parses JSON if the Content-Type is application/json
data = request.json
print(f"Received data: {data}")
return jsonify({"status": "success"}), 200

if **name** == '**main**':
app.run(port=5000)

Node.js with Express

Node.js is widely used for server-side development, and Express is one of the most popular frameworks for Node.js.

const express = require("express");
const bodyParser = require("body-parser");

const app = express();

// Middleware to parse JSON payload from incoming POST request
app.use(bodyParser.json());

app.post("/webhook", (req, res) => {
  // req.body contains the parsed JSON payload
  const data = req.body;
  console.log(`Received data: ${JSON.stringify(data)}`);
  res.status(200).json({ status: "success" });
});

app.listen(3000, () => {
  console.log("Server started on <http://localhost:3000>");
});

Ruby with Sinatra

Sinatra is a DSL (Domain Specific Language) for quickly creating web applications in Ruby with minimal effort.

require 'sinatra'
require 'json'

post '/webhook' do # Reading and parsing the JSON payload from the request body
  data = JSON.parse(request.body.read)
  puts "Received data: #{data}"
  [200, { 'Content-Type' => 'application/json' }, { status: 'success' }.to_json]
end

Deployment

After setting up your webhook endpoint, you’ll need to deploy it. You can use cloud services like AWS, Google Cloud, Heroku, or any VPS provider for this purpose.

Secure your Webhook

You may validate incoming requests to ensure they are coming from a trusted source. Visit our webhooks signature for more information. This is a recommended best practice.

Test your Webhook

After deployment, you can test your webhook endpoint using Postman or curl to send a simulated POST request.