Skip to main content

Setting up a webhook

This guide will explain how to receive messages about Radom payments, subscriptions, invoices and more.

How Radom uses webhooks​

Radom uses webhooks to provide real-time information about all Radom activity. This enables you to deliver products to your users after receiving successful payments or enable a subscription after a successful payment.

Radom sends messages as a JSON payload via POST request to all active registered webhooks. Webhooks currently receive data about all notifications.

For each message that is not successfully sent, Radom will attempt retries every up to a maximum of 9 times. You can also view the webhook messages in the Developer Webhook page in the Radom Dashboard by clicking on a webhook and trigger retries if needed.

Webhook event samples​

{
  "eventType": "managedPayment",
  "eventData": {
    "managedPayment": {
      "paymentMethod": {
        "network": "SolanaDevnet",
        "token": null
      },
      "amount": "0.05174000000",
      "transactions": [
        {
          "network": "SolanaDevnet",
          "transactionHash": "Biqv82rkELugxVFVUrcobxabNvUztxno9vCBDLdnQUzBqNmacbMKtuSAF9srJPQq8CWpA47rpL8skkt2MTEsZvk",
          "token": null,
          "amount": "0.0520",
          "blockTimestamp": "2023-06-06T06:11:42Z"
        }
      ]
    }
  },
  "radomData": {
    "paymentLink": {
      "paymentLinkId": "9353ac9f-d44e-4acf-a18e-83189422363a",
      "paymentLinkOrderId": "aa697c4e-c489-4dd4-813d-1f9e8ad19745"
    }
  }
}

Steps to receive webhook messages​

  1. Create an HTTPS server with a POST endpoint that returns a HTTP 200 status code.
  2. Register the webhook in the Radom dashboard using the endpoint's URL.
  3. Identify and resend webhook message failures.
  4. Update or pause a webhook.

Step 1. Create a webhook HTTPS endpoint​

Create a web application with a webhook endpoint. The endpoint should respond to a POST request which handles the message object data delivered in a JSON payload. The endpoint must respond with HTTP 200 status code.

The header should be checked for a verification_key, which will be randomly generated and provided when registering a webhook.

Below is some sample code to help get started with receiving POST requests from Radom:

// Installation:
// npm i express body-parser util

const express = require('express')
const bodyParser = require('body-parser');
const util = require('util')

const app = express()

app.use(bodyParser.urlencoded({ extended: false }))
app.use(bodyParser.json())

const port = 9999

// Generated when creating the webhook endpoint in the Radom dashboard
const verificationKey = "webhook_verification_key"

app.post('/webhook', (req, res) => {
  if (req.headers["radom-verification-key"] != verificationKey) {
    return res.sendStatus(401)
  }

  console.log(util.inspect(req.body, false, null, true /* enable colors */))

  res.sendStatus(200)
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

Step 2. Register a webhook​

Use the Developer Section in the Radom dashboard to register your webhook endpoint. Alternatively, create the webhook through the API.

Step 3. Handle webhook message failures​

Use the Developer Section in the Radom dashboard to reset webhook failures so that Radom will attempt to send the messages again. This can be done for all or individual webhook failures.

Step 4. Updating and pausing a webhook​

Use the Developer Section in the Radom Dashboard configuration in the Radom dashboard to update a webhook. Alternatively, update the webhook ​through the API.