Overview

import httpx, uuid

response = httpx.post(
    "https://api.natural.com/webhooks",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "data": {
            "attributes": {
                "url": "https://yourdomain.com/hooks/natural",
                "enabledEvents": ["wallet.created", "party.updated"],
            }
        }
    },
)
webhook = response.json()["data"]
signing_secret = webhook["attributes"]["signingSecret"]  # shown once, store securely

const response = await fetch("https://api.natural.com/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    data: {
      attributes: {
        url: "https://yourdomain.com/hooks/natural",
        enabledEvents: ["wallet.created", "party.updated"],
      },
    },
  }),
});
const webhook = (await response.json()).data;
const signingSecret = webhook.attributes.signingSecret; // shown once, store securely

curl -X POST https://api.natural.com/webhooks \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "url": "https://yourdomain.com/hooks/natural",
        "description": "Production webhook",
        "enabledEvents": ["wallet.created", "party.updated"],
        "tags": { "env": "prod" }
      }
    }
  }'

import os
from fastapi import FastAPI, Request, HTTPException, BackgroundTasks
from standardwebhooks import Webhook

app = FastAPI()
wh = Webhook(os.environ["NATURAL_WEBHOOK_SECRET"])  # the whsec_... value

@app.post("/hooks/natural")
async def handle(request: Request, background_tasks: BackgroundTasks):
    body = await request.body()  # raw bytes, required for verification
    try:
        event = wh.verify(body, dict(request.headers))
    except Exception:
        raise HTTPException(status_code=401, detail="Invalid signature")
    # Hand off async work and return 2xx fast.
    background_tasks.add_task(process_event, event, request.headers["webhook-id"])
    return {"received": True}

import express from "express";
import { Webhook } from "standardwebhooks";

const app = express();
const wh = new Webhook(process.env.NATURAL_WEBHOOK_SECRET!); // the whsec_... value

// express.raw keeps the body as exact bytes for verification.
app.post("/hooks/natural", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body, req.headers as Record<string, string>);
  } catch {
    return res.status(401).send("Invalid signature");
  }
  // Hand off async work and return 2xx fast.
  void processEvent(event, req.headers["webhook-id"]);
  res.json({ received: true });
});