Skip to main content

Integrating with Webhooks

Listen for messages about product purchase agreements associated with your organization's wallet address so your integration can automatically trigger reactions.

How Radom uses webhooks

Radom uses webhooks to provide real-time information about all on-chain Radom smart contract activity that impacts product purchase agreements. This enables providers to create integrations for synchronization of the state of their products and services with purchaser configuration and funding.

Radom sends messages via POST request to webhooks registered by an organization for every change on every product purchase agreement. For each message, the seller wallet address is used to determine the webhook to which the message is sent.

For each message that is not confirmed to be sent successfully, Radom will attempt retries every 20 minutes for 3 hours. If Radom detects the webhook as offline for 1 day, message failure retries are disabled. If a webhook is paused then messages will not be sent, but they will be saved as webhook failures to be sent later. If a webhook is offline or paused for over 30 days messages will not be sent and additionally webhook failures will no longer be saved.

Webhook message object

"service_offer_id": 1000001,
"service_agreement_id": 1,
"purchaser_address": "0x6ca83bc387eea5b14bb2fb86cc4c075650563909",
"seller_address": "0xb946ea0de6c749ac6999c0fc6e8f415bdd052338",
"authentication_string": "123.abc_d",
"action": "CREATED",
"user_expiry_timestamp": "2022-12-28T02:41:40",
"string_data": {},
"options_data": { {} },
"base_cost_per_hour": 123.45,
"additional_cost_per_hour": 1.23,
"token_symbol": "USDC"

Steps to receive webhook messages

  1. Create a webhook endpoint to handle POST requests from Radom by returning 200 response status code.
  2. Registering a webhook with publicly accessible URI.
  3. Identify and resend webhook message failures.
  4. Update or pause a webhook.

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 action field in the message object describes the Radom subscription agreement events: CREATED, UPDATED, DELETED.

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 koa koa-body

const Koa = require('koa')
const { koaBody } = require('koa-body')

const app = new Koa()


jsonLimit: '1kb'

app.use(async ctx => {
switch (ctx.request.method) {
case 'POST':

const handlePost = ctx => {
const radom_verification_key = ctx.request.header["radom_verification_key"]
if (radom_verification_key === undefined) {
ctx.throw(400, 'No verification key header')
if (radom_verification_key != RADOM_VERIFICATION_KEY) {
ctx.throw(400, 'Invalid verification key')
console.log('Received POST request')
ctx.body = ''


2. Register a webhook

Use the Organization configuration in the Radom dashboard to register the URI/URL of your server running your webhook application. Alternatively, create the webhook through the API.

3. Handle webhook message failures

Use the Organization configuration 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. Alternatively, resend all webhook failures for a webhook, or resend individual webhook failures through the API.

Webhook behavior

Resending webhook failures will disable the offline flag on the webhook.

4. Updating and pausing a webhook

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