Skip to main content

Setting up a webhook

This guide explains how to receive messages about Radom payments, subscriptions, invoices, deposits, payouts, and other supported events.

How Radom uses webhooks​

Radom uses webhooks to provide real-time event notifications for activity in your organization. This allows you to deliver products after a successful payment, reconcile deposits and payouts, or update internal systems when subscriptions or invoices change state.

Radom sends messages as JSON payloads in POST requests to each active registered webhook endpoint.

If your endpoint does not return a successful 2xx response, Radom retries delivery up to 4 additional times, for up to 5 delivery attempts total. You can also inspect webhook messages in the Developer Webhooks page in the Dashboard and retry failed deliveries manually 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 successful HTTP 2xx status code.
  2. Register the webhook in the Radom dashboard using the endpoint's URL.
  3. Review and retry webhook delivery failures when needed.
  4. Update or pause a webhook.

Step 1. Create a webhook HTTPS endpoint​

Create a web application with a webhook endpoint. The endpoint should handle a POST request containing the JSON payload sent by Radom. The endpoint should return a successful 2xx response after the payload has been accepted.

Validate the radom-verification-key request header against the verification key that Radom generates when you register the webhook.

Below is sample code to help you get started with receiving webhook 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 inspect failed deliveries and retry them. This can be done for all failures or on individual messages.

Step 4. Updating and pausing a webhook​

Use the Developer Section in the Radom Dashboard to update, pause, or resume a webhook. Alternatively, update the webhook ​through the API.