Overview

A webhook is a URL you register so Natural can push Events to your server as they happen, instead of you polling for changes. When a payment completes, a deposit lands, or a customer connects, Natural sends the event to your URL. Each webhook subscribes to the event types you choose, every delivery is signed with the webhook’s secret so you can verify it came from Natural, and failed deliveries are retried. Natural signs every delivery with the Standard Webhooks spec; verify it before trusting the payload. See the Event catalog for every event type and its full payload.

1. Register an endpoint

POST /webhooks registers your URL and subscribes it to event types. The signing secret is returned once in the response; store it immediately.

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" }
      }
    }
  }'

enabledEvents accepts any event type from the Event catalog, or the wildcard "*" (which must be the only entry). description and tags are optional.

The signingSecret (whsec_...) appears only in this response. If you lose it, rotate it with POST /webhooks/{webhookId} /rotate-secret.

2. Verify the signature

Every delivery is a POST whose JSON body is the event object. Three signature headers ride on each delivery (lowercase, per the Standard Webhooks spec):

Header	Description
`webhook-id`	The event ID (`evt_...`), stable across retries. Use for idempotency.
`webhook-timestamp`	Unix epoch seconds when the delivery was signed.
`webhook-signature`	One or more space-separated `v1,<base64>` signatures.

Always verify before trusting a payload. Use the official standardwebhooks library (Python and Node); construct it with your whsec_ secret and pass the raw body plus headers. verify returns the parsed event, or raises on a bad signature:

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 });
});

Verify against the raw request body, the exact bytes Natural sent. Parsing and re-serializing the JSON first changes the bytes and breaks verification.

The library handles two details for you: it rejects deliveries whose webhook-timestamp is outside a tolerance window (replay defense), and it accepts a delivery if any of the space-separated signatures verifies, which is what lets a secret rotation overlap two valid secrets.

Verify manually, without the library

The signed content is the string {webhook-id}.{webhook-timestamp}.{body}. Strip the whsec_ prefix from the secret, base64-decode the remainder for the HMAC key, compute HMAC-SHA256, and base64-encode the result. Compare it against each space-separated v1,<sig> entry.

import base64, hashlib, hmac

def verify(body: bytes, headers: dict, signing_secret: str) -> bool:
    key = base64.b64decode(signing_secret.removeprefix("whsec_"))
    signed = f"{headers['webhook-id']}.{headers['webhook-timestamp']}.{body.decode()}"
    expected = base64.b64encode(hmac.new(key, signed.encode(), hashlib.sha256).digest()).decode()
    for entry in headers["webhook-signature"].split(" "):
        version, _, sig = entry.partition(",")
        if version == "v1" and hmac.compare_digest(sig, expected):
            return True
    return False

import { createHmac, timingSafeEqual } from "crypto";

function verify(body: string, headers: Record<string, string>, signingSecret: string): boolean {
  const key = Buffer.from(signingSecret.replace(/^whsec_/, ""), "base64");
  const signed = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${body}`;
  const expected = Buffer.from(createHmac("sha256", key).update(signed).digest("base64"));
  return headers["webhook-signature"].split(" ").some((entry) => {
    const [version, sig] = entry.split(",");
    if (version !== "v1" || !sig) return false;
    const sigBuf = Buffer.from(sig);
    return sigBuf.length === expected.length && timingSafeEqual(sigBuf, expected);
  });
}

3. Delivery, retries & failures

Natural treats any 2xx response as success. The delivery request times out after 30 seconds. Failed deliveries (non-2xx, network error, or timeout) are retried up to 7 attempts total with jittered backoff (~20% jitter):

Attempt	Delay after previous
1	immediate
2	5 seconds
3	5 minutes
4	30 minutes
5	2 hours
6	8 hours
7	12 hours

An endpoint that fails every attempt for 5 consecutive events is automatically disabled. Re-enable it with PATCH /webhooks/{webhookId} once your endpoint is healthy.

Best practices

Return 2xx fast. Acknowledge as soon as the signature verifies, then process the event asynchronously; slow handlers risk the 30-second timeout and trigger retries.
Deduplicate on webhook-id. Retries reuse the same webhook-id, and Natural may deliver an event more than once; record processed IDs and skip duplicates.
Store the whsec_ secret in a secrets manager, never in source control. Rotate it with POST /webhooks/{webhookId}/rotate-secret; the previous secret stays valid for the grace period you specify, so both signatures arrive during the overlap.
Don’t depend on event ordering. Retries and independent delivery mean events can arrive out of order; use the version field on the resource snapshot, or refetch the resource, when ordering matters.

Agents

Customers

Payments

Transactions

Transfers

Payment Requests

Approvals

Limits

Parties

Party Invitations

Wallets

Wallet Access

External Accounts

API keys

Agent keys

Webhooks

Events

Errors

Overview

1. Register an endpoint

2. Verify the signature

3. Delivery, retries & failures

Best practices

​1. Register an endpoint

​2. Verify the signature

​3. Delivery, retries & failures

​Best practices

1. Register an endpoint

2. Verify the signature

3. Delivery, retries & failures

Best practices