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
- Create a webhook endpoint to handle POST requests from Radom by returning 200 response status code.
- Registering a webhook with publicly accessible URI.
- Identify and resend webhook message failures.
- 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:
- Node
- Rust
// Installation:
// npm i koa koa-body
const Koa = require('koa')
const { koaBody } = require('koa-body')
const app = new Koa()
const RADOM_VERIFICATION_KEY = "OTA3MzBkNzctNTYxZi00NTkwLThjMjEtOGE0NWYzMDAwZDllMHg2Y2E4M2JjMzg3ZWVhNWIxNGJiMmZiODZjYzRjMDc1NjUwNTYzOTA5"
app.use(koaBody({
jsonLimit: '1kb'
}))
app.use(async ctx => {
switch (ctx.request.method) {
case 'POST':
handlePost(ctx)
break
default:
break
}
})
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 = ''
}
app.listen(3001)
// Installation:
// cargo add actix-web
use actix_web::{
http::header::HeaderName, web, App, HttpRequest, HttpResponse, HttpServer, Responder,
};
use std::{net::TcpListener};
static RADOM_VERIFICATION_KEY: &str = "OTA3MzBkNzctNTYxZi00NTkwLThjMjEtOGE0NWYzMDAwZDllMHg2Y2E4M2JjMzg3ZWVhNWIxNGJiMmZiODZjYzRjMDc1NjUwNTYzOTA5";
#[actix_web::main]
async fn main() -> Result<(), std::io::Error> {
let listener = TcpListener::bind("localhost:3001")?;
let server = HttpServer::new(move || {
App::new().route("/webhook_endpoint", web::post().to(handle_post))
})
.listen(listener)?
.run();
server.await
}
async fn handle_post(req: HttpRequest) -> impl Responder {
println!("Received POST request");
let radom_verification_key = HeaderName::from_lowercase(b"radom_verification_key").unwrap();
match req.headers().get(radom_verification_key) {
Some(v) => {
if v != RADOM_VERIFICATION_KEY {
return HttpResponse::BadRequest().finish();
}
}
None => return HttpResponse::BadRequest().finish(),
}
HttpResponse::Ok().finish()
}
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.
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.