Skip to main content
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: Set Webhook

​
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 TypeDescription
charge_successThe user has charged successfully
charge_failedThe user could not be charged
token_transfer_pendingThe transfer of onramped tokens has been started
token_transfer_successThe onramped tokens have been transferred successfully
account_not_associatedThe account that was to receive the onramped tokens was not associated to the token
token_transfer_failedThe transfer of onramped tokens failed