How do you receive Rodz leads by webhook and verify their HMAC signature?

Before you start

• A Rodz API key and its webhook secret: Integrations → API in the dashboard (the secret can be regenerated there).
• A signal linked to that API key (created with it through the API): with no key linked, deliveries go out unsigned.
• A public HTTPS URL for your server (a tunnel is enough during development).
• Node.js 18+ with Express 4, or Python 3.10+ with FastAPI.

Steps

1. Step 1. Get the webhook secret

   In the Rodz dashboard, open Integrations → API. Each API key has a webhook secret generated automatically. Copy it into a RODZ_WEBHOOK_SECRET environment variable, never into the code.

2. Step 2. Write the receiver in Node.js

   The key point: read the raw body (express.raw), because the signature covers the exact bytes sent. The receiver checks the signature, refuses a timestamp older than 5 minutes, skips a delivery it has already seen, answers 200 and then processes the lead.

   node/server.js

   // Rodz webhook receiver (Node.js 18+, Express 4).
   const express = require('express');
   const crypto = require('crypto');
   
   const SECRET = process.env.RODZ_WEBHOOK_SECRET;
   const TOLERANCE_SECONDS = 300;
   const seen = new Set(); // in production: Redis or your database
   
   function isValid(rawBody, signature, timestamp) {
     if (!signature || !timestamp) return false;
     const expected = crypto
       .createHmac('sha256', SECRET)
       .update(Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]))
       .digest('hex');
     const a = Buffer.from(expected, 'utf8');
     const b = Buffer.from(signature, 'utf8');
     return a.length === b.length && crypto.timingSafeEqual(a, b);
   }
   
   async function handleLead(lead) {
     if (lead.signal && lead.signal.is_test) return console.log('test payload received');
     // Your logic: CRM, message queue, database...
     console.log(lead.signal.type, lead.company && lead.company.name);
   }
   
   const app = express();
   app.post('/webhooks/rodz', express.raw({ type: 'application/json', limit: '1mb' }), (req, res) => {
     const signature = req.get('X-Webhook-Signature');
     const timestamp = req.get('X-Webhook-Timestamp');
     if (!isValid(req.body, signature, timestamp)) return res.status(401).send('invalid signature');
     if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) {
       return res.status(401).send('stale timestamp');
     }
   
     const deliveryId = req.get('X-Webhook-Id');
     if (deliveryId && seen.has(deliveryId)) return res.status(200).send('duplicate');
     if (deliveryId) seen.add(deliveryId);
   
     const lead = JSON.parse(req.body.toString('utf8'));
     res.status(200).send('ok'); // answer first
     setImmediate(() => handleLead(lead).catch(console.error)); // then process
   });
   
   app.listen(process.env.PORT || 3000);

3. Step 3. Or write it in Python

   Same logic with FastAPI: await request.body() gives the raw bytes, hmac.compare_digest compares in constant time, and a background task processes the lead after the response.

   python/app.py (uvicorn app:app)

   # Rodz webhook receiver (Python 3.10+, FastAPI).
   import hashlib
   import hmac
   import json
   import os
   import time
   
   from fastapi import BackgroundTasks, FastAPI, Request, Response
   
   SECRET = os.environ["RODZ_WEBHOOK_SECRET"].encode("utf-8")
   TOLERANCE_SECONDS = 300
   seen: set[str] = set()  # in production: Redis or your database
   
   app = FastAPI()
   
   
   def is_valid(body: bytes, signature: str, timestamp: str) -> bool:
       if not signature or not timestamp:
           return False
       message = f"{timestamp}.".encode("utf-8") + body
       expected = hmac.new(SECRET, message, hashlib.sha256).hexdigest()
       return hmac.compare_digest(expected, signature)
   
   
   def handle_lead(lead: dict) -> None:
       if lead.get("signal", {}).get("is_test"):
           print("test payload received")
           return
       company = lead.get("company") or {}
       print(lead["signal"]["type"], company.get("name"))
   
   
   @app.post("/webhooks/rodz")
   async def rodz_webhook(request: Request, tasks: BackgroundTasks) -> Response:
       body = await request.body()
       signature = request.headers.get("X-Webhook-Signature", "")
       timestamp = request.headers.get("X-Webhook-Timestamp", "")
       if not is_valid(body, signature, timestamp):
           return Response("invalid signature", status_code=401)
       if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
           return Response("stale timestamp", status_code=401)
   
       delivery_id = request.headers.get("X-Webhook-Id")
       if delivery_id and delivery_id in seen:
           return Response("duplicate", status_code=200)
       if delivery_id:
           seen.add(delivery_id)
   
       tasks.add_task(handle_lead, json.loads(body))
       return Response("ok", status_code=200)

4. Step 4. Connect the signal and send a test

   Save your URL as the signal’s webhookUrl (at creation, or with PATCH /api/v1/signals/{signal_id}). Then call POST /api/v1/signals/{signal_id}/test-webhook: with a {"url": "..."} body you test another address before saving it. The response gives success, your server’s statusCode, the payloadSent (with signal.is_test set to true) and signed: false means no API key is linked to the signal.

   Test the receiver

   curl -X POST "https://api.rodz.io/api/v1/signals/$SIGNAL_ID/test-webhook" \
     -H "Authorization: Bearer $RODZ_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"url": "https://hooks.example.com/webhooks/rodz"}'

5. Step 5. Recover from an outage with replay-webhook

   If your server was down for longer than the retries, POST /api/v1/signals/{signal_id}/replay-webhook resends every lead the signal has produced, with signal.is_replay set to true. The response gives total, sent and failed. Your deduplication stops the same lead from being created twice. For a simple catch-up without a webhook, GET /api/v1/signals/{signal_id}/leads?since=... reads the leads directly.

   Resend the signal’s leads

   curl -X POST "https://api.rodz.io/api/v1/signals/$SIGNAL_ID/replay-webhook" \
     -H "Authorization: Bearer $RODZ_API_KEY"

Example payload

Excerpt of a request as your server receives it: headers, then the JSON body. The `signal` fields vary with the signal type; `contact` is `""` for a lead without a person; `signal.is_test` only appears on a test.

POST /webhooks/rodz HTTP/1.1
Content-Type: application/json
X-Webhook-Id: 7f3c2a9e-1b4d-4c8e-9a01-5d6e7f8a9b0c
X-Webhook-Timestamp: 1760256000
X-Webhook-Signature: 3b1f0c...e9a4 (64 hex characters)

{
  "signal": {
    "id": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
    "name": "Series A+ in France",
    "type": "fundraising",
    "last_signal": "Fundraising",
    "last_signal_date": "2026-10-12",
    "is_test": true,
    "funding_stage": "Series A",
    "funding_amount_usd": 5500000,
    "announcement_date": "2026-10-10"
  },
  "contact": "",
  "company": {
    "name": "Northwind Robotics",
    "website": "https://northwind-robotics.example",
    "linkedin_url": "https://www.linkedin.com/company/northwind-robotics-example",
    "hq_country_code": "FR",
    "hq_city": "Nantes"
  }
}

Frequently asked questions

Sources

• Rodz API reference: webhooks, signature, retries, test-webhook and replay-webhook
• RFC 2104: HMAC, keyed-hashing for message authentication
• Express: express.raw()

Related guides

• API recipe How do you pull a Rodz signal’s leads through the API, without a webhook?
• API recipe How do you create a Rodz signal and route it to lemlist, entirely through the API?
• Recipe How do you send funding rounds detected by Rodz to an n8n workflow?
• About this signal All signals