Onramp Webhook

After initializing a payment request you can listen for events from our platform on the webhook URL you entered. To enter a webhook URL for a specific environment, navigate to the Settings > Webhooks page on the dashboard and enter the webhook URL as shown below:

Create a Webhook URL

A POST request is sent to your webhoook URL, with a JSON body containing information about the webhook event. A response with a status code of 200 should be returned in your webhook endpoint to indicate that your system has processed our event.

You should avoid long running tasks in your webhook endpoint, if there are long running tasks you can return the response early

An example of how you can process the webhook events sent to your endpoint:

WebHookHandler.js

// POST ENDPOINT FOR YOUR WEBHOOK
app.post("/your/webhook/endpoint", async (req, res) => {
    const webhookBody = req.body; // Get webhook event data

    // Process data

    res.status(200).send("Done"); // Return 200 response
})

The webhook event data looks like this:

{
  event_type: string;
  order_id: <orderid-given-when-initializing-payment>;
  token: <token-you-indicated-to-receive>;
  amount: <amount-user-paid>;
  currency: <currency-user-pay-in> | null;
  failureReason?: <optional-further-explanation-incase-failure>;
}

Verify Event Origin

Since your webhook URL is publicly available, you need to verify that events originate from Orion and not a bad actor. You can validate the signature in the event request’s headers to do this. Events sent by Orion have the x-orion-signature header. The value is a HMAC SHA512 signature of the event request body signed using the webhook secret shown in your dashboard. Verifying that this signature is correct should be done before processing the event. Below is an example of how you can validate the signature:

validateSignature.js

import crypto from "crypto";
const webhookSecret = "your-webhook-secret";

function validateSignature(signature, eventPayload) {
  const hash = crypto.createHmac('sha512', webhookSecret).update(JSON.stringify(eventPayload)).digest('hex');
  if (hash === signature) {
    return true
  }

  return false
}

Supported Events

The list below shows the possible webhook event types that can be returned:

Event Type	Description
charge_success	The user has charged successfully
charge_failed	The user could not be charged
token_transfer_pending	The transfer of onramped tokens has been started
token_transfer_success	The onramped tokens have been transferred successfully
account_not_associated	The account that was to receive the onramped tokens was not associated to the token
token_transfer_failed	The transfer of onramped tokens failed

Getting started

Endpoint examples

Webhook

Create a Webhook URL

Verify Event Origin

Supported Events

​Create a Webhook URL

​Verify Event Origin

​Supported Events

Create a Webhook URL

Verify Event Origin

Supported Events